> ## 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.

# HCTraceCallback

> Callback that receives libHttpClient trace messages so that a game can merge them into its own logs.

# HCTraceCallback

Receives libHttpClient trace messages so that a game can merge them into its own logs.

## Syntax

```cpp theme={null}
void CALLBACK HCTraceCallback(  
         const char* areaName,  
         HCTraceLevel level,  
         uint64_t threadId,  
         uint64_t timestamp,  
         const char* message  
)  
```

### Parameters

*areaName*   \_In\_z\_\
Type: const char\*

Null-terminated name of the trace area that produced the message. libHttpClient uses the `HTTPCLIENT` and `WEBSOCKET` areas. Libraries that build on libHttpClient, such as the XBOX services API (XSAPI), report their own areas, for example `XSAPI`.

*level*   \_In\_\
Type: [HCTraceLevel](https://docs.xbox.com/reference/live/httpclient/trace/enums/hctracelevel.md)

Trace level of the message.

*threadId*   \_In\_\
Type: uint64\_t

ID of the thread that produced the message. On Windows PC and XBOX consoles, this value is the operating system thread ID that `GetCurrentThreadId` returns.

*timestamp*   \_In\_\
Type: uint64\_t

Time of the message, in milliseconds since the most recent initialization that started tracing, that is, the [HCInitialize](https://docs.xbox.com/reference/live/httpclient/httpclient/functions/hcinitialize.md) or [HCTraceInit](https://docs.xbox.com/reference/live/httpclient/trace/functions/hctraceinit.md) call that changed the tracing reference count from zero to one.

*message*   \_In\_z\_\
Type: const char\*

Null-terminated, formatted trace message. The message doesn't include the thread, level, time, and area prefix that libHttpClient adds to debugger output.

### Return value

Type: void

## Remarks

Register the callback by calling [HCTraceSetClientCallback](https://docs.xbox.com/reference/live/httpclient/trace/functions/hctracesetclientcallback.md).

libHttpClient calls the callback synchronously on the thread that produced the trace message. Several threads can call the callback at the same time, so make the callback thread-safe and return quickly.

The *areaName* and *message* strings are valid only for the duration of the call. Copy them if you need them later.

libHttpClient calls the callback only for messages at or below the verbosity of the message's trace area. To change the verbosity of the libHttpClient trace areas, call [HCSettingsSetTraceLevel](https://docs.xbox.com/reference/live/httpclient/trace/functions/hcsettingssettracelevel.md).

Each direct call to [HCTraceCleanup](https://docs.xbox.com/reference/live/httpclient/trace/functions/hctracecleanup.md) removes all registered client callbacks. Library cleanup also removes them when the final cleanup of libHttpClient reaches trace cleanup. Removing the registrations doesn't wait for a callback that's already running. Register the callback again after you reinitialize libHttpClient.

## Example

The following example assumes that [HCInitialize](https://docs.xbox.com/reference/live/httpclient/httpclient/functions/hcinitialize.md) already succeeded.

```cpp theme={null}
void CALLBACK TraceCallback(
    _In_z_ char const* areaName,
    HCTraceLevel level,
    uint64_t threadId,
    uint64_t timestamp,
    _In_z_ char const* message
)
{
    // Forward the message to the game's logging system.
}

HCSettingsSetTraceLevel(HCTraceLevel::Verbose);
if (!HCTraceSetClientCallback(TraceCallback))
{
    // Registration failed. Report the failure through the game's logging or error handling.
}
```

## Requirements

**Header:** trace.h

**Library:** libHttpClient.lib

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## See also

[trace](https://docs.xbox.com/reference/live/httpclient/trace/trace_members.md)\
[HCTraceSetClientCallback](https://docs.xbox.com/reference/live/httpclient/trace/functions/hctracesetclientcallback.md)\
[HCSettingsSetTraceLevel](https://docs.xbox.com/reference/live/httpclient/trace/functions/hcsettingssettracelevel.md)\
[HCTraceLevel](https://docs.xbox.com/reference/live/httpclient/trace/enums/hctracelevel.md)\
[Troubleshooting XBOX services APIs](https://docs.xbox.com/services/xbox-services/develop/troubleshooting/live-troubleshooting-apis.md)


## Related topics

- [HCTraceSetClientCallback](https://docs.xbox.com/reference/live/httpclient/trace/functions/hctracesetclientcallback.md)
- [trace (contents)](https://docs.xbox.com/reference/live/httpclient/trace/trace_members.md)
- [HCTracePlatformThisThreadIdCallback](https://docs.xbox.com/reference/live/httpclient/trace/functions/hctraceplatformthisthreadidcallback.md)
- [HCTraceSetPlatformCallbacks](https://docs.xbox.com/reference/live/httpclient/trace/functions/hctracesetplatformcallbacks.md)
- [HCTracePlatformWriteMessageToDebuggerCallback](https://docs.xbox.com/reference/live/httpclient/trace/functions/hctraceplatformwritemessagetodebuggercallback.md)