WsCreateHeap function

Creates a heap object.

Syntax

HRESULT WINAPI  WsCreateHeap(
  _In_     SIZE_T                  maxSize,
  _In_     SIZE_T                  trimSize,
  _In_opt_ const WS_HEAP_PROPERTY* properties,
  _In_     ULONG                   propertyCount,
           WS_HEAP**               heap,
  _In_opt_ WS_ERROR*               error
);

Parameters

maxSize [in]

The total number of bytes that can be allocated from the heap. The total number of bytes is defined as sum of the sizes passed in all the calls to the WsAlloc function since the heap was created or reset.

trimSize [in]

The maximum number of bytes of memory that the heap retains after the heap has been reset by a call to the WsResetHeap function. This is an approximation value due to heap overhead.

Note  If the value of trimSize is larger than the value of maxSize, the size of the heap will not be adjusted to the desired size.

 

properties [in, optional]

Reserved for future use; set to NULL.

propertyCount [in]

Reserved for future use; set to 0 (zero).

heap

On success, pointer that receives the address of the WS_HEAP structure representing the new heap object.

error [in, optional]

Pointer to a WS_ERROR structure that receives additional error information if the function fails.

Return value

If the function succeeds, it returns NO_ERROR; otherwise, it returns an HRESULT error code.

Remarks

A heap in Windows Web Services API is a memory allocation used for messages. Heaps can also be used to store message data separately from the lifetime of a message. Some API functions allow for explicit heap control over the lifetime of any data read.

Creating new heap does not allocate any memory (except the memory necessary for WS_HEAP structure itself). The parameters maxSize and trimSize are used as quotas onlyduring WsAlloc and WsResetHeap operations.

Requirements