> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XblMemAllocFunction

> Defines a callback that allocates memory for the XBOX Services API (XSAPI).

# XblMemAllocFunction

A callback that the XBOX Services API (XSAPI) invokes each time it needs a new memory buffer.

## Syntax

```cpp theme={null}
typedef _Ret_maybenull_ _Post_writable_byte_size_(size) void*  
(STDAPIVCALLTYPE* XblMemAllocFunction)(  
         _In_ size_t size,  
         _In_ HCMemoryType memoryType  
);  
```

### Parameters

*size*   \_In\_\
Type: size\_t

The size of the allocation to be made. This value is never zero.

*memoryType*   \_In\_\
Type: HCMemoryType

An opaque identifier that represents the internal category of memory being allocated.

### Return value

Type: void\*

A pointer to an allocated block of memory of the specified size, or a null pointer if the allocation failed.

## Remarks

This callback is optional. Install it, together with an [XblMemFreeFunction](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblmemfreefunction.md) callback, by calling [XblMemSetFunctions](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblmemsetfunctions.md) before you call [XblInitialize](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblinitialize.md). Both callbacks must be set together.

The callback must allocate and return a pointer to a contiguous block of memory of the specified size. The block must remain valid until XSAPI passes the pointer to the corresponding `XblMemFreeFunction` callback. Every non-null pointer that the callback returns is passed to the `XblMemFreeFunction` callback when XSAPI no longer needs the memory.

`XblMemSetFunctions` also passes the callbacks to libHttpClient. If libHttpClient is already initialized, it keeps its existing memory hooks.

If you install custom memory callbacks, wait for [XblCleanupAsync](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblcleanupasync.md) to complete before you shut down your memory manager. If your app dispatches XSAPI work concurrently, make sure that any allocator state shared by the callbacks is safe for concurrent use.

The following example installs callbacks that use `malloc` and `free` from `<stdlib.h>`.

```cpp theme={null}
void* STDAPIVCALLTYPE MyXblAlloc(_In_ size_t size, _In_ HCMemoryType memoryType)
{
    UNREFERENCED_PARAMETER(memoryType);
    return malloc(size);
}

void STDAPIVCALLTYPE MyXblFree(_In_ _Post_invalid_ void* pointer, _In_ HCMemoryType memoryType)
{
    UNREFERENCED_PARAMETER(memoryType);
    free(pointer);
}

HRESULT hr = XblMemSetFunctions(MyXblAlloc, MyXblFree);
if (FAILED(hr))
{
    // Handle the error before you call XblInitialize.
}
```

## Argument of

[XblMemSetFunctions](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblmemsetfunctions.md)\
[XblMemGetFunctions](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblmemgetfunctions.md)

## Requirements

**Header:** xbox\_live\_global\_c.h

**Library:** Microsoft.Xbox.Services.142.C.lib or Microsoft.Xbox.Services.143.C.lib

## See also

[xbox\_live\_global\_c](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/xbox_live_global_c_members.md)\
[XblMemFreeFunction](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblmemfreefunction.md)


## Related topics

- [XblMemFreeFunction](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblmemfreefunction.md)
- [XblMemSetFunctions](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblmemsetfunctions.md)
- [XblMemGetFunctions](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblmemgetfunctions.md)
- [xbox_live_global_c (contents)](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/xbox_live_global_c_members.md)
- [HCMemAllocFunction](https://docs.xbox.com/reference/live/httpclient/httpclient/functions/hcmemallocfunction.md)