Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method returns an upper bound on the number of bytes needed to marshal the specified interface pointer on the specified object.

Syntax 

HRESULT GetMarshalSizeMax(
  REFIID 
riid,
  void* 
pv,
  DWORD 
dwDestContext,
  void* 
pvDestContext,
  DWORD 
mshlflags,
  ULONG* 
pSize 
);

Parameters

riid

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

pv

[in] Interface pointer to be marshaled; can be NULL.

dwDestContext

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

Values for dwDestContextcome from the enumeration MSHCTX.

Currently, 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] Flag indicating 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 MSHLFLAGSenumeration.

pSize

[out] Pointer to the upper bound on the amount of data to be written to the marshaling stream.

Return Value

The method supports the standard return value E_FAIL, as well as the following:

S_OK

The maximum size was returned successfully.

E_NOINTERFACE

The specified interface was not supported.

Remarks

This method is called indirectly, in a call to CoGetMarshalSizeMax, 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. An examples is the IClassFactoryinterface.

For purposes of discussion, the code responsible for marshaling a pointer is here 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 CoGetMarshalSizeMaxand CoMarshalInterface.

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

Notes to Callers

The marshaling stub, through a call to CoGetMarshalSizeMax, calls the object's implementation of this method to preallocate the stream buffer that will be passed to IMarshal::MarshalInterface.

You do not explicitly call this method if you are:

  • Implementing existing COM interfaces, or

  • Defining your own custom interfaces, using the Microsoft® Interface Definition Language (MIDL).

In both cases, the MIDL-generated stub automatically makes the call.

If you are not using MIDL to define your own interface (see Defining COM Interfaces), your marshaling stub does not have to call GetMarshalSizeMax, although doing so is highly recommended.

An object knows better than an interface stub what the maximum size of a marshaling data packet is likely to be. Therefore, unless you are providing an automatically growing stream that is so efficient that the overhead of expanding it is insignificant, call this method even when implementing your own interfaces.

The value returned by this method is only guaranteed to be valid as long as the internal state of the object being marshaled does not change. Therefore, the actual marshaling should be done immediately after this function returns, or the stub runs the risk that the object, because of some change in state, might require more memory to marshal than it originally indicated.

Notes to Implementers

Your implementation of MarshalInterfacewill use this buffer to write marshaling data into the stream.

If the buffer is too small, the marshaling operation will fail. Therefore, the value returned by this method must be a conservative estimate of the amount of data that is needed to marshal the interface. Violation of this requirement should be treated as a catastrophic error.

In a subsequent call to IMarshal::MarshalInterface, your IMarshalimplementation cannot rely on the caller actually having called GetMarshalSizeMaxbeforehand. It must still be wary of STG_E_MEDIUMFULL errors returned by the stream and be prepared to handle them gracefully.

To ensure that your implementation of GetMarshalSizeMaxwill continue to work properly as new destination contexts are supported in the future, delegate marshaling to COM's default implementation for all dwDestContextvalues that your implementation does not understand.

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

Requirements

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also