IMarshal::GetUnmarshalClass method (objidl.h)

Article
10/13/2021

Retrieves the CLSID of the unmarshaling code.

Syntax

HRESULT GetUnmarshalClass(
  [in]  REFIID riid,
  [in]  void   *pv,
  [in]  DWORD  dwDestContext,
  [in]  void   *pvDestContext,
  [in]  DWORD  mshlflags,
  [out] CLSID  *pCid
);

Parameters

[in] riid

A reference to the identifier of the interface to be marshaled.

[in] pv

A pointer to the interface to be marshaled; can be NULL if the caller does not have a pointer to the desired interface.

[in] dwDestContext

The destination context where the specified interface is to be unmarshaled. Possible values come from the enumeration MSHCTX. Unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).

[in] pvDestContext

This parameter is reserved and must be NULL.

[in] mshlflags

Indicates whether the data to be marshaled is to be transmitted back to the client process (the typical case) or written to a global table, where it can be retrieved by multiple clients. Possible values come from the MSHLFLAGS enumeration.

[out] pCid

A pointer that receives the CLSID to be used to create a proxy in the client process.

Return value

If the method succeeds, the return value is S_OK. Otherwise, it is S_FALSE.

Remarks

This method is called indirectly, in a call to CoMarshalInterface, by whatever code in the server process is responsible for marshaling a pointer to an interface on an object. This marshaling code is usually a stub generated by COM for one of several interfaces that can marshal a pointer to an interface implemented on an entirely different object. Examples include the IClassFactory and IOleItemContainer interfaces. For purposes of discussion, the code responsible for marshaling a pointer is called the marshaling stub.

To create a proxy for an object, COM requires two pieces of information from the original object: the amount of data to be written to the marshaling stream and the proxy's CLSID.

The marshaling stub obtains these two pieces of information with successive calls to CoGetMarshalSizeMax and CoMarshalInterface.

Notes to Callers

The marshaling stub calls the object's implementation of this method to obtain the CLSID to be used in creating an instance of the proxy. The client, upon receiving the CLSID, loads the DLL listed for it in the system registry.

You do not explicitly call this method if you are implementing existing COM interfaces or using the Microsoft Interface Definition Language (MIDL) to define your own interfaces. In either case, the stub automatically makes the call. See Defining COM Interfaces.

If you are not using MIDL to define your own interface, your stub must call this method, either directly or indirectly, to get the CLSID that the client-side COM library needs to create a proxy for the object implementing the interface.

If the caller has a pointer to the interface to be marshaled, it should, as a matter of efficiency, use the pv parameter to pass that pointer. In this way, an implementation that may use such a pointer to determine the appropriate CLSID for the proxy does not have to call QueryInterface on itself. If a caller does not have a pointer to the interface to be marshaled, it can pass NULL.

Notes to Implementers

COM calls GetUnmarshalClass to obtain the CLSID to be used for creating a proxy in the client process. The CLSID to be used for a proxy is normally not that of the original object, but one you will have generated (using the Guidgen.exe tool) specifically for your proxy object.

Implement this method for each object that provides marshaling for one or more of its interfaces. The code responsible for marshaling the object writes the CLSID, along with the marshaling data, to a stream; COM extracts the CLSID and data from the stream on the receiving side.

If your proxy implementation consists simply of copying the entire original object into the client process, thereby eliminating the need to forward calls to the original object, the CLSID returned would be the same as that of the original object. This strategy, of course, is advisable only for objects that are not expected to change.

If the pv parameter is NULL and your implementation needs an interface pointer, it can call QueryInterface on the current object to get it. The pv parameter exists merely to improve efficiency.

To ensure that your implementation of GetUnmarshalClass continues to work properly as new destination contexts are supported in the future, delegate marshaling to the COM default implementation for all dwDestContext values that your implementation does not handle. To delegate marshaling to the COM default implementation, call the CoGetStandardMarshal function.

Note The ThreadingModel registry value must be Both for an in-process server that implements the CLSID returned from the GetUnmarshalClass method. For more information, see InprocServer32.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps \| UWP apps]
Minimum supported server	Windows 2000 Server [desktop apps \| UWP apps]
Target Platform	Windows
Header	objidl.h

Share via