XSAPI C libraries
The Library line on each XSAPI C reference page names the static libraries. The GDK provides these XSAPI C libraries:
Each library also has a
.Debug variant. When you link a static library, also link libHttpClient.lib, the import library for libHttpClient.dll. Copy libHttpClient.dll, and Microsoft.Xbox.Services.C.Thunks.dll if you use the DLL, from the GDK bin folder into your game’s layout. For the full list of libraries, see GDK directory structure.
Benefits of the C API for XSAPI
- Allows titles to control the memory allocations when calling XSAPI.
- Allows titles to gain full control of thread handling when calling XSAPI.
- Uses a new HTTP library, libHttpClient, designed for game developers.
Managing memory allocations
With the C API, you can now specify a function callback that XSAPI will call whenever it tries to allocate memory. If you do not specify function callbacks, XSAPI will use standard memory allocation routines. To manually specify your memory routines, you can do the following:- At the start of the game:
- Call
XblMemSetFunctions(memAllocFunc, memFreeFunc)to specify the allocation callbacks for assigning and releasing memory. - Call
XblInitialize()to initialize the library instance.
- Call
- While the game is running:
- Calling any of the new C APIs in XSAPI that allocate or free memory will cause XSAPI to call the specified memory handling callbacks.
- When the game exits:
- Wait for your outstanding XSAPI calls to finish, and then call XblCleanupAsync and wait for it to finish. This reclaims all resources associated with the XSAPI library.
- Clean up your game’s custom memory manager.
Managing asynchronous threads
The C API introduces a new asynchronous thread calling pattern that allows developers full control over the threading model. For more information, see Calling pattern for XSAPI C layer async calls.Migrating code to use C XSAPI
The XSAPI C APIs can be used alongside the XSAPI C++ APIs in a project, so we recommend that you migrate one feature at a time. The C APIs and C++ APIs are really just thin wrappers around a common core, just with different entry points, so the functionality should be unchanged. However, only the C APIs can take advantage of the custom memory and thread management features.Useful resources
- Samples using the XSAPI C APIs
- libHttpClient GitHub repo
- To view the C APIs, see the XSAPI C header files. It is in the XBOX services SDK which is part of the GDK.