Setting and Getting a Log Token for a Thread

SetupAPI logging supports a mechanism that establishes a log context for a thread. This context is established by setting a log token for the thread. SetupAPI provides this mechanism so that code that is called by a thread can write log entries to the log context of the calling thread.

For example, a thread can set a log token for its log context before it calls a class installer or co-installer. The installer, in turn, can retrieve the calling thread's log token and use that token to write log entries in the text log and section that is associated with the calling thread's log context.

Setting a log token for a thread

The SetupSetThreadLogToken function sets a log token for the thread from which this function was called. The log token can either be a system-defined log token or a log token that was retrieved by calling SetupGetThreadLogToken.

The following are examples of how a log context can be established for a thread:

• An installation application can call SetupSetThreadLogToken to establish a log context for other installation code that runs within the same thread. When it is establishing the log context for the thread, the application should use a system-defined log token, such as LOGTOKEN_SETUPAPI_APPLOG, in the call to SetupSetThreadLogToken.

  Note  If the log context is set by using a system-defined log token, subsequent calls to a SetupAPI logging function that are made from that log context, write log entries to the installation text log, which are not part of a text log section.

• If a class installer or co-installer starts a new thread, the installer can set the log context for that thread to be the same as the parent thread. This is done in the following way:

  1. Before the parent thread starts the new thread, it acquires the current log token by calling SetupGetThreadLogToken.
  2. The parent thread starts the new thread and passes the current log token through an implementation-specific method, such as saving the token in a global variable.
  3. The new thread calls SetupSetThreadLogToken with the current log token. As a result, the new thread "inherits" the log context of the parent thread.

  Note  If a thread of a class installer or co-installer sets the log context by using this method, subsequent calls to a SetupAPI logging function that are made from that log context write log entries to the installation text log that may be part of a text log section. This only happens if a text log section was established by the SetupAPI installation operation that called the installer.

The following is an example of a call to SetupSetThreadLogToken that sets the log context of the current thread to the device installation text log (SetupAPI.app.log) by specifying the system-defined log token of LOGTOKEN_SETUPAPI_APPLOG. A subsequent call to a SetupAPI logging function that uses this log context would write the log entry to the device installation text log, but not as part of a text log section.

SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);

Getting a log token for a thread

The SetupGetThreadLogToken function retrieves a log token for the thread from which this function was called.

For example, a class installer can call SetupGetThreadLogToken to retrieve the log token that applies to the SetupAPI operation that called the class installer. The class installer can then use this retrieved log token to log entries in the text log that applies to the corresponding SetupAPI operation.

Note  If the log context of a thread was not previously set by a call to SetupSetThreadLogToken, a call to SetupGetThreadLogToken returns a log token with a value of LOGTOKEN_UNSPECIFIED.

The following is an example of a call to SetupGetThreadLogToken that retrieves the log token for the current thread.

SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();