4.3 IRemUnknown::RemAddRef

Obtain and grant ownership to the caller of one or more reference counts on one or more IPIDs managed by the corresponding OXID.

Argument Type Semantic
cInterfaceRefs unsigned short       The size of the rgRefs array.
InterfaceRefs REMINTERFACEREF[]    An array of REMINTERFACEREFs, cRefs large. Each IPID indicates an interface managed by this OXID on whom more reference counts are sought. The corresponding reference count (cInterfaceRefs), which may not be zero (and thus is one or more), indicates the number of reference counts sought on that IPID.
pResults HRESULT* An array of HRESULTs cInterfaceRefs large, each containing the result of attempting an AddRef on the ipid in the corresponding REMINTERFACREF.

ReturnValue Meaning
S_OK           Success. An attempt was made to retrieve each of the requested interface references.
E_INVALIDARG   One or more of the IPIDs indicated were not in fact managed by this OXID, or one or more of the requested reference counts was zero. None of the requested reference counts have been granted to the caller; the call is a no-op.
E_UNEXPECTED   An unspecified error occurred. It is unknown whether any or all of the requested reference counts have been granted.  CO_E_OBJNOTREG Object is not registered.  A useful optimization is for a caller to RemAddRef more than needed.

When a process receives an out marshaled interface, it receives one reference count. If the process wishes to pass that interface as an out parameter, it must get another reference to pass along. Instead, the process (or middleman) should get a large number of references. Then if the interface is passed out multiple times, no new remote calls are needed to gain additional references.

A marshaler may optionally specify more than one reference in the STDOBJREF when marshaling an interface. This allows the middle man case to pre-fill its cache of references without making an extra RemAddRef call. The number of references passed is always specified in the STDOBJREF field.

If cPrivateRefs is not zero for all IPIDs, the call to RemAddRef must be made securely.  DCOM on the server remembers the name of the client and the authentication and authorization service used to make to RemAddRef call.

4.3.1 REMINTERFACEREF

Member Type Semantic
Ipid IPID Ipid to AddRef/Release.
CPublicRefs Unsigned long Number of public references granted.
CPrivateRefs Unsigned long Number of private references granted.  Private references belong only to this client and can not be passed to other clients when marshaling the proxy. If a client has only private references and wishes to pass the proxy to some other client, it must first obtain some public references via IRemUnknown::RemAddRef and then pass one or more of those references in the STDOBJREF cPublicRefs field of the marshaled interface.