IMarshal::GetUnmarshalClass

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method returns the CLSID that COM uses to locate the DLL containing the code for the corresponding proxy. COM loads this DLL to create an uninitialized instance of the proxy.

Syntax

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

Parameters

• riid
  [in] Reference to the identifier of the interface to be marshaled.

• pv
  [in] Pointer to the interface to be marshaled; can be NULL if the caller does not have a pointer to the desired interface.

• dwDestContext
  [in] Destination context where the specified interface is to be unmarshaled.

  Values for dwDestContext 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).

• pvDestContext
  [in] Reserved for future use; must be NULL.

• mshlflags
  [in] 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. Valid values come from the MSHLFLAGS enumeration.

• pCid
  [out] Pointer to the CLSID to be used to create a proxy in the client process.

Return Value

Returns S_OK if successful; otherwise, S_FALSE.

Remarks

This method is called by whatever code in the server process can be 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. An example is the IClassFactory interface. For this 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.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

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
• Defining your own interfaces using the Microsoft Interface Definition Language (MIDL).

In both cases, 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 can 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 typically not that of the original object (see Notes to Implementers for the exception), 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 IUnknown::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 COM's default implementation for all dwDestContext values that your implementation does not handle.

To delegate marshaling to COM's default implementation, call the CoGetStandardMarshal function.

Requirements

See Also

Reference

CoGetMarshalSizeMax
CoGetStandardMarshal
CoMarshalInterface
IClassFactory
IUnknown::QueryInterface