RpcSsAllocate

The RpcSsAllocate function allocates memory within the RPC stub memory management function, and returns a pointer to the allocated memory or NULL.

#include <rpc.h>
void __RPC_FAR * RPC_ENTRY RpcSsAllocate( 
  size_t  Size  
);
 

Parameters

Size
Specifies the size of memory to allocate (in bytes).

Remarks

The RpcSsAllocate routine allows an application to allocate memory within the RPC stub memory management function. Prior to calling RpcSsAllocate, the memory management environment must already be established. For memory management called within the stub, the stub itself usually establishes the necessary environment. See Chapter 8, "Memory Management," for a complete discussion of the various memory management conditions supported by RPC. When using RpcSsAllocate to allocate memory not called from the stub, the application must call RpcSsEnableAllocate to establish the required memory management environment.

The RpcSsAllocate routine returns a pointer to the allocated memory, if the call was successful. Otherwise, it raises an exception.

When the stub establishes the memory management, it frees any memory allocated by RpcSsAllocate. The application can free such memory before returning to the calling stub by calling RpcSsFree.

By contrast, when the application establishes the memory management, it must free any memory allocated. It does so by calling either RpcSsFree or RpcSsDisableAllocate.

To manage the same memory within the stub memory management environment, multiple threads can call RpcSsAllocate and RpcSsFree. In this case, the threads must share the same stub memory management thread handle. Applications pass thread handles from thread to thread by calling RpcSsGetThreadHandle and RPCSsSetThreadHandle.

Note  The RpcSsAllocate routine raises exceptions, while the RpcSmAllocate routine returns the error code.

Return Values

Value Meaning
RPC_S_OUT_OF_MEMORY Out of memory

QuickInfo

  Windows NT: Yes
  Windows CE: Unsupported.
  Header: Declared in rpcndr.h.
  Import Library: Link with rpcrt4.lib.

See Also

RpcSmAllocate, RpcSsDisableAllocate, RpcSsEnableAllocate, RpcSsFree, RpcSsGetThreadHandle, RpcSsSetThreadHandle