LlmConnectEx

LlmConnectEx Function

HCLIENT WINAPI LlmConnectEx(

DWORD dwProviderId,

DWORD dwOptions,

LPLLM_SESSION lpSession

);

The LlmConnectEx function establishes a connection to the specified large language model service provider using an extended session configuration.

Parameters

dwProviderId

Specifies the service provider. This parameter must be one of the LLM_PROVIDER constants. See the remarks below for more information about service providers.

dwOptions

Specifies one or more option flags that control how the connection is established. This parameter can be zero or a combination of LLM_OPTION values. These options control behavior such as connection security, proxy usage, and HTTP connection handling.

Value Description

LLM_OPTION_NONE A standard connection to the server is established using the default behavior for the selected provider. No additional options are enabled, and the connection will use the provider's default protocol, caching behavior and request headers.

LLM_OPTION_NOCACHE Disables provider and model metadata caching for the client session. When this option is specified, the library will not reuse cached metadata, and provider or model information will be retrieved from the server each time it is required. This may be useful when testing or when current data is required.

LLM_OPTION_KEEPALIVE Enables persistent HTTP connections using the keep-alive mechanism. When enabled, the underlying HTTP connection may be reused for multiple requests, reducing connection overhead and improving performance. If this option is not specified, the connection may be closed after each request.

LLM_OPTION_PROXY Specifies that the connection should be made using the current Windows proxy server configuration. If the user does not have a proxy server configuration, this option is ignored. This option is typically used in environments where direct internet access is restricted.

LLM_OPTION_NOUSERAGENT Prevents the library from sending a User-Agent header with requests to the provider. By default, a User-Agent string is included to identify the client. This option may be used when a provider does not require a User-Agent header.

LLM_OPTION_SECURE Forces the use of a secure HTTPS connection when communicating with the provider. If the specified base URL or provider default would normally use an insecure protocol, it will be upgraded to a secure connection. Connections to providers such as OpenAI, Google and Anthropic will always be secure.

LLM_OPTION_DEFAULT Specifies the default option set, which is equivalent to LLM_OPTION_NONE. No additional flags are enabled and the connection uses standard behavior.

lpSession

A pointer to an LLM_SESSION structure that specifies extended configuration options for the client session. This structure can be used to define parameters such as the base URL, model name, authentication information, timeout values, token limits and sampling settings.

Return Value

If the function succeeds, the return value is a handle to a client session. If the function fails, the return value is INVALID_CLIENT. To get extended error information, call LlmGetLastError.

Remarks

The LlmConnectEx function creates a client session using the configuration specified in the lpSession structure. This provides more control over how the connection is established compared to LlmConnect, and is intended for applications that require advanced configuration.

The dwProviderId parameter specifies the numeric identifier assigned to a supported provider. Provider identifiers are predefined constants built into the library and are assigned fixed values beginning at 1 and increasing sequentially for each provider. These identifiers are stable and are intended to uniquely identify a provider regardless of its display name. Applications should use the predefined constants (such as LLM_PROVIDER_OPENAI or LLM_PROVIDER_MICROSOFT) rather than hard-coding numeric values directly in source code.

Refer to the providers page for a list of supported service providers and their default models.

The lpSession structure allows the application to specify connection parameters such as the provider endpoint, model name, API key, timeout values, token limits and sampling options. Any values not explicitly specified will use provider defaults.

Applications using languages other than C or C++ may find it easier to create and manage session structures using the LlmCreateSession, LlmCreateSessionEx and LlmDeleteSession functions. These helper functions allocate and initialize a compatible structure that can be passed to this function.

The library makes an internal copy of the string members in the LLM_SESSION structure when the connection is established. The application does not need to retain them after the call to LlmConnectEx returns.

This function will block the calling thread until the connection has been established or the timeout period has elapsed. Applications should avoid calling this function on the main user interface thread. For best results, create a worker thread to establish the connection, especially when multiple connections are required.

The connection established by this function represents a logical session. Depending on the provider and options specified, the underlying HTTP connection may be reused across requests or recreated as needed. Options such as LLM_OPTION_KEEPALIVE can be used to control connection behavior.

The client handle returned by this function is owned by the thread that created it. To transfer ownership to another thread, use the LlmAttachThread function.

Example

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

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

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

    // Additional options such as temperature, token limits and timeouts
    // can be configured using members of the LLM_SESSION structure
    LLM_SESSION sessionInfo;

    ZeroMemory(&sessionInfo, sizeof(sessionInfo));
    sessionInfo.dwSize = sizeof(sessionInfo);
    sessionInfo.lpszModelName = _T("gpt-5.4-nano");
    sessionInfo.lpszApiKey = _T("%OPENAI_API_KEY%");
    sessionInfo.lpszSystemPrompt = _T("You are a helpful assistant.");

    // Establish a connection to OpenAI using a lightweight model
    // with the default connection options
    hClient = LlmConnectEx(LLM_PROVIDER_OPENAI,
                           LLM_OPTION_DEFAULT,
                           &sessionInfo);

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

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

    // Send a simple message to the model
    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);
    }

    // Clean up
    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