6.2 The IRemoteActivation Interface

IRemoteActivation is defined as follows:

[
    uuid(4d9f4ab8-7d1c-11cf-861e-0020af6e7c57),
    pointer_default(unique)
]

interface IRemoteActivation
{
    import "obase.idl";

    const unsigned long MODE_GET_CLASS_OBJECT = 0xffffffff;

    HRESULT RemoteActivation(
     [in] handle_t        hRpc,
     [in] ORPCTHIS       *ORPCthis,
     [out] ORPCTHAT      *ORPCthat,
     [in] GUID *Clsid,
     [in, string, unique] WCHAR                 *pwszObjectName,
     [in, unique] MInterfacePointer             *pObjectStorage,
     [in] DWORD ClientImpLevel,
     [in] DWORD Mode,
     [in] DWORD Interfaces,
     [in,unique,size_is(Interfaces)] IID        *pIIDs,
     [in] unsigned short  cRequestedProtseqs,
     [in, size_is(cRequestedProtseqs)]
          unsigned short  RequestedProtseqs[],
     [out] OXID*pOxid,
     [out] DUALSTRINGARRAY                     **ppdsaOxidBindings,
     [out] IPID*pipidRemUnknown,
     [out] DWORD         *pAuthnHint,
     [out] COMVERSION    *pServerVersion,
     [out] HRESULT       *phr,
     [out,size_is(Interfaces)] MInterfacePointer **ppInterfaceData,
     [out,size_is(Interfaces)] HRESULT          *pResults
     );
}

6.2.1 IRemoteActivation::RemoteActivation

Activates the class object specified by Clsid, associated with the pwszObjectName file moniker, or associated with pObjectStorage -- a client- provided IStorage object --, and gives the client the OXID and IPID(s) of any interfaces it requested on that object. Implementations are free to return a new instance of the requested class object every time this API is called or to return the same class object (i.e. the same OXID and IPIDs) every time.  Implementations may choose to offer "launch" functionality by loading and initializing the executable code which implements the requested class object if it is not already running, or if the programmer wishes to have objects segregated into different processes because of security or robustness considerations.

This function incorporates the functionality of both the IRemUnknown and IOXIDResolver interfaces so that only one network roundtrip is necessary for object activation.

Argument Type Description
hRpc handle_t            An RPC binding handle used to make the request.
ORPCthis ORPCTHIS*           Client-provided ORPCTHIS
ORPCthat ORPCTHAT* Server-provided ORPCTHAT
Clsid const GUID*         The CLSID of the class object the caller wishes to activate.
pwszObjectName WCHAR*              Path to a file name which when activated by the server's moniker facility, will return the object that the client is interested in.
pObjectStorage MInterfacePointer*  Interface pointer to an object on the client which supports IStorage.  The server on the remote will use the IStorage's CLSID to determine which object to instantiate on the server.
ClientImpLevel DWORD A value taken from the RPC_C_IMP constants. Used to inform the server of the client's default impersonation level.
Mode DWORD Set to MODE_GET_CLASS_OBJECT for regular object activations. If pwszObjectName or pObjectStorage are not NULL, this mode is passed to IPersistFile::Load when activating the object on the  server. 
Interfaces DWORD The number of interfaces being requested
PIIDs IID* The list of IIDs that name the interfaces sought on this object.
cRequestedProtseqs Unsigned short      The number of protocol sequences specified in the RequestedProtseqs parameter.
RequestedProtseqs Unsigned short[]    The list of protocol sequences that the client wants OXID binding handles for.
pOxid OXID*               The OXID for the object created.
ppdsaOxidBindings DUALSTRINGARRAY**   Endpoint and security binding strings to reach the OXID
pipidRemUnknown IPID* The IPID of the OXID's IremUnknown interface
pAuthnHint DWORD*              A value taken from the RPC_C_AUTHN constants. A hint to the caller as to the minimum authentication level which the server will accept.
pServerVersion COMVERSION* The version of the COM implementation on the server.
phr HRESULT* The HRESULT for the activation operation
ppInterfaceData MInterfacePointer** The set of interface pointers requested. Returned in the order they were requested in pIIDs.
pResults HRESULT*            The HRESULTs for the individual QueryInterface() operations performed on the interfaces specified in Interfaces.

ReturnValue Meaning
RPC_S_OK             This method always  returns RPC_S_OK. Check phr for the status of this function.

Value of phr Meaning
E_UNEXPECTED         An unspecified error occurred
E_ACCESSDENIED       Client attempted to activate but did not have the required permission or the server does not permit remote activations
E_INVALIDARG         One or more arguments are invalid.
E_OUTOFMEMORY        Insufficient memory to complete the operation.