WsCreateHeap function (webservices.h)

Article
10/13/2021

Creates a heap object.

Syntax

HRESULT WsCreateHeap(
  [in]           SIZE_T                 maxSize,
  [in]           SIZE_T                 trimSize,
  [in, optional] const WS_HEAP_PROPERTY *properties,
  [in]           ULONG                  propertyCount,
                 WS_HEAP                **heap,
  [in, optional] WS_ERROR               *error
);

Parameters

[in] maxSize

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.

[in] trimSize

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.

[in, optional] properties

Reserved for future use; set to NULL.

[in] propertyCount

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.

[in, optional] error

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

Requirement	Value
Minimum supported client	Windows 7 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 R2 [desktop apps \| UWP apps]
Target Platform	Windows
Header	webservices.h
Library	WebServices.lib
DLL	WebServices.dll

Share via