### ICountedPointerTo

  Creates a templatized smart pointer with automatic reference counting. ICountedPointerTo provides a smart C++ like pointer with this additional built-in behavior: when you create an instance of ICountedPointerTo, it automatically calls IMRefCounted::addRef on the object pointed to; when the ICountedPointerTo is destroyed, it calls IMRefCounted::removeRef to removes its reference to the object.

  ICountedPointerTo also allows you to perform reference counting on objects that do not descend from IMRefCounted. In this case, it encloses, or wraps, the object in a reference-counted wrapper.

### ICountedPointerTo - Member Functions and Data by Group

### Constructors & Destructor

Use these functions to construct, copy, and destruct counted pointer objects.

~ICountedPointerTo
  Destroys the counted pointer.

      public:
      ~ICountedPointerTo()

  This destructor destroys the counted pointer and decrements the reference count of the object pointed to. When the count is zero, the object is deleted.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

ICountedPointerTo
  This function constructs an object of class ICountedPointerTo.

  Overload 1
  Copies a counted pointer.

      public:
      ICountedPointerTo(const ICountedPointerTo < AType >& share)

  Use this constructor to create a copy of the given counted pointer. The constructor increments the reference count of the object pointed to by the given counted pointer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2
  Construct a counted pointer object.

      public:
      ICountedPointerTo()

  Use this function to construct an object that points to nothing. This function is slightly more efficient than calling ICountedPointerTo(0).

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 3
  Constructs an ICountedPointerTo that points to the given object.

      public:
      ICountedPointerTo(AType* adopt)

  Use this constructor to create an object of class ICountedPointerTo that points to the object specified by the adopt parameter. This constructor adopts the given object and increments its reference count. Use the newly constructed instance of ICountedPointer to make any further references to the object pointed to. Discard the raw pointer used to specify the adopted object. constructor.

  adopt
    A pointer to the object to be pointed to from the constructed object of class ICountedPointerTo.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Accessing an Object

Use these functions to access the pointer being counted.

getAlias
  Returns a raw C++ pointer to the object to which this points.

      public:
      AType* getAlias() const

  This function returns a raw C++ pointer to the object to which this points.

  If this pointer does not refer to an object, the function returns zero.

  Use this function to pass a raw C++ pointer to an existing function that expects one. Do not continue to use the pointer after this ICountedPointerTo object has been destroyed.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operator *
  Returns a reference to the object pointed to.

      public:
      AType& operator *() const

  This operator returns a reference to the object referred to by the counted pointer.

Exception

  IInvalidRequest | Thrown when your code attempts to dereference a null pointer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operator ->
  Returns the object pointed to.

      public:
      AType* operator ->() const

  This operator is called when you use a counted pointer with the C++ class member access operator ->.

Exception

  An | IInvalidRequest exception is thrown when your code attempts to dereference a null pointer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Changing the Object Pointed to

Use these functions to point this counted pointer object at another object.

operator =
  This operator modifies the counted pointer so that it refers to a different object from the one it currently points to.

  Overload 1
  Changes the object pointed to.

      public:
      ICountedPointerTo < AType >&
        operator =( const ICountedPointerTo < AType >& share )

  Use this operator to modify the counted pointer so that it refers to the same object as another counted pointer. If the object the pointer previously referred to was a valid object, that object's reference count is decremented. When the count is zero, that object is deleted.

  share
    A counted pointer to the new target object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2
  Changes the object pointed to.

      public:
      ICountedPointerTo < AType >& operator =(AType* adopt)

  Use this operator to modify the counted pointer so that it refers to the given object to be adopted. If the object the pointer previously referred to was a valid object, that object's reference count is decremented. The object is deleted when its reference count is zero.

  The function adopts the given object and increments its reference count. Make all further references to the given object through this ICountedPointer object. Discard the raw pointer used to specify the adopted object.

  adopt
    The object to be pointed to. The operator assigns the adopted object to the instance of ICountedPointerTo and increments the object's reference count.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Comparing and Testing the Pointer

Use these functions to determine whether this object points to a particular object or the same object that another counted pointer object also points to, and whether the pointer is valid or not.

operator !=
  This function determines whether the counted pointer refers to a particular object.

  Overload 1
  Determines whether this pointer refers to the given object.

      public:
      bool operator !=(const AType* r) const

  Use this function to determine if this counted pointer refers to the given object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2
  Determines whether this pointer refers to the same object as another counted pointer.

      public:
      bool
        operator !=( const ICountedPointerTo < AType >& r ) const

  Use this function to determine if this counted pointer refers to the same object as another counted pointer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operator ==
  This operator determines whether this pointer refers to a particular object.

  Overload 1
  Determines whether this pointer refers to the same object as another counted pointer.

      public:
      bool
        operator ==( const ICountedPointerTo < AType >& r ) const

  Use this operator to determine if this counted pointer refers to the same object as another counted pointer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2
  Determines whether this pointer refers to the given object.

      public:
      bool operator ==(const AType* r) const

  Use this function to determine if this counted pointer refers to the given object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

valid
  Queries whether this counted pointer refers to a valid object.

      public:
      bool valid() const

  This function returns true if this counted pointer refers to a valid, non-null object. Otherwise it returns false.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

validate
  Asserts that this pointer refers to a valid object.

      public:
      void validate() const

  This function asserts that this counted pointer refers to a valid object. If it does not, the function throws an exception.

Exception

  IInvalidRequest | This pointer does not refer to a valid object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Obtaining and Counting Object References

Use these methods to manage the reference count of an object.

count
  Returns the current reference count.

      public:
      unsigned long count() const

  This function returns the reference count of the object to which this counted pointer refers. If this counted pointer does not refer to a valid object, it returns zero.

  Note that when the counted pointer refers to an object that does not inherit from IMRefCounted, this function returns the reference count of the internal wrapper around that object

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### ICountedPointerTo - Inherited Member Functions and Data

#### Inherited Public Functions

  IMStreamable

  -     virtual ~IMStreamable()

  -     void externalizeToStream(IDataStream& towhere) const

  -     void internalizeFromStream(IDataStream& fromwhere)

  -     virtual const ITypeRepresentation&
          typeRepresentation() const = 0

  ICountedPointerTo

  -     IMRefCounted* getCounted() const

  -     void
          in( AType* r,
              IVoidMasterPointer* indirect,
              IMRefCounted* )

  -     void in(AType* r, IVoidMasterPointer* indirect, void*)

  -     static bool isWrapped()

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IMStreamable

  -     IMStreamable()

  -     IMStreamable(const IMStreamable& other)

  -     virtual void readFromStream(IDataStream& fromwhere) = 0

  -     virtual void writeToStream(IDataStream& towhere) const = 0

#### Inherited Protected Data

  - None