LlmCreateSession

LlmCreateSession Function

BOOL WINAPI LlmCreateSession(

DWORD dwProviderId,

LPCTSTR lpszBaseUrl,

LPCTSTR lpszModelName,

LPCTSTR lpszApiKey,

LPCTSTR lpszApiVersion,

LPLLM_SESSION *lppSession

);

The LlmCreateSession function allocates and initializes an LLM_SESSION structure using the specified connection parameters.

Parameters

dwProviderId

Specifies the service provider. This parameter must be one of the LLM_PROVIDER constants. Refer to the providers page for a list of supported providers and their default models.

lpszBaseUrl

A pointer to a null-terminated string that specifies the base URL for the provider endpoint. This parameter may be NULL to use the default endpoint for the selected provider. Some providers, such as Microsoft Foundry or local services, require a specific base URL.

lpszModelName

A pointer to a null-terminated string that specifies the model name to use for the session. This parameter may be NULL to use the provider default model, if one is defined. Providers without a default model require an explicit model name.

lpszApiKey

A pointer to a null-terminated string that specifies the API key used to authenticate with the provider. The API key may be provided using a literal string, an environment variable, or a value stored in the Windows Credential Manager. Using an environment variable or secure credential storage is recommended for production applications to avoid exposing sensitive information in source code or application binaries.

lpszApiVersion

A pointer to a null-terminated string that specifies the API version required by the provider. This parameter may be NULL if the provider does not require an explicit version. Some providers, such as Microsoft and Anthropic, may require a version string when establishing a connection.

lppSession

A pointer to a variable that receives a pointer to an allocated LLM_SESSION structure. On successful return, this parameter will contain a pointer to a structure that can be passed to LlmConnectEx. The structure must be released using the LlmDeleteSession function when it is no longer needed.

Return Value

If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. To get extended error information, call LlmGetLastError.

Remarks

The LlmCreateSession function is a helper function that allocates and initializes an LLM_SESSION structure using the specified parameters. This simplifies working with session structures, particularly in languages that do not easily support structure initialization or require explicit memory management. This function is typically used in conjunction with LlmConnectEx when an application requires extended session configuration.

The structure returned by this function is allocated by the library and must be released using the LlmDeleteSession function. Failing to release the structure will result in a memory leak.

Applications using languages that do not support pointer-to-pointer parameters may treat the lppSession parameter as an opaque pointer value. In this case, the variable should be defined using an integer type that is large enough to hold a pointer value, such as UINT_PTR or an equivalent type. Applications must ensure that the correct pointer size is used for the target platform.

Once a connection has been established using LlmConnectEx, the session structure is no longer required and may be released using LlmDeleteSession. The library creates an internal copy of the session configuration, so the original structure does not need to remain allocated for the lifetime of the client session.

Example

#include "cstools12.h"
#include <stdio.h>

int _tmain(void)
{
    HCLIENT hClient = INVALID_CLIENT;
    LPLLM_SESSION lpSession = NULL;
    DWORD dwError = NO_ERROR;

    // Initialize the SocketTools library
    if (!LlmInitialize(CSTOOLS12_LICENSE_KEY, NULL))
    {
        _tprintf(_T("Initialization failed: %lu\n"), LlmGetLastError());
        return 1;
    }

    // Create a session structure using helper function
    if (!LlmCreateSession(LLM_PROVIDER_OPENAI,
                         NULL,                      // Default URL
                         _T("gpt-5.4-nano"),        // Model name
                         _T("%OPENAI_API_KEY%"),    // API key
                         NULL,                      // API version
                         &lpSession))
    {
        dwError = LlmGetLastError();
        _tprintf(_T("Unable to create session, error %lu\n"), dwError);
        LlmUninitialize();
        return 1;
    }

    // Establish a connection using the session structure
    hClient = LlmConnectEx(LLM_PROVIDER_OPENAI,
                           LLM_OPTION_DEFAULT,
                           lpSession);

    if (hClient == INVALID_CLIENT)
    {
        dwError = LlmGetLastError();
        _tprintf(_T("Unable to connect, error %lu\n"), dwError);

        // Clean up session before exit
        LlmDeleteSession(&lpSession);
        LlmUninitialize();
        return 1;
    }

    // The session structure is no longer needed after connecting
    LlmDeleteSession(&lpSession);

    TCHAR szResponse[4096] = {0};
    DWORD dwResponseLength = _countof(szResponse);
    DWORD dwMessageId = 0;

    if (LlmSendMessage(hClient,
                       _T("What is the capital city of Denmark?"),
                       szResponse,
                       &dwResponseLength,
                       &dwMessageId))
    {
        _tprintf(_T("Response:\n%s\n"), szResponse);
    }
    else
    {
        dwError = LlmGetLastError();
        _tprintf(_T("Request failed, error %lu\n"), dwError);
    }

    LlmDisconnect(hClient);
    LlmUninitialize();

    return 0;
}

Requirements

Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools12.h
Import Library: csllmv12.lib
Unicode: Implemented as Unicode and ANSI versions

Parameters

Return Value

Remarks

Example

Requirements

See Also