LlmConnect

LlmConnect Function

HCLIENT WINAPI LlmConnect(

DWORD dwProviderId,

DWORD dwOptions,

INT nTimeout,

LPCTSTR lpszBaseUrl,

LPCTSTR lpszModelName,

LPCTSTR lpszApiKey

);

The LlmConnect function establishes a connection to the specified large language model service provider and creates a client session.

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 the following values:

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.

nTimeout

The timeout period for connection and request operations, in seconds. A value of zero indicates that the default timeout should be used.

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. This typically includes models accessed using the Microsoft Foundry or locally hosted inference providers.

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.

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 LlmConnect function creates a client session that is used for all subsequent operations with the selected provider. The returned handle maintains the connection settings, authentication information, selected model, and conversation history for the session.

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.

If the lpszBaseUrl parmeter is NULL or a zero-length string, the library will use a provider-specific default endpoint. Some providers, such as Microsoft Foundry services or locally hosted models, require an explicit endpoint and will fail if one is not provided.

If the lpszModelName parameter is NULL or a zero-length string, the library will attempt to use a default model for the selected provider. Not all providers define a default model, and in those cases an explicit model name must be provided when establishing the connection. This typically includes models accessed using the Microsoft Foundry or locally hosted inference providers.

If the service provider requires authentication, the API key can be provided in several formats, allowing applications to provide credentials in a way that balances convenience and security:

Literal string
The API key is provided directly as a string. This is the simplest approach and is convenient for testing or small internal tools, but it is not recommended for production applications. A literal key may be exposed in source code, configuration files, diagnostic logs or the compiled application binary.

Environment variable
The name of an environment variable enclosed in percent symbols, for example "%OPENAI_API_KEY%". The value of the environment variable is used as the API key. This avoids embedding the key directly in the application and is useful for development, scripts and deployment environments. However, environment variables may still be visible to the current user, inherited by child processes or exposed through system configuration, so they should still be protected appropriately.

Windows credential
A credential name enclosed in braces, for example "{MyAppName/OpenAI}". The API key is retrieved from the Windows Credential Manager using the specified name. This is the recommended approach for most Windows applications because the secret is stored outside the application and managed by the operating system. The credential can be created manually using Credential Manager, or programmatically by the application using the Windows Credential Management API. Applications should choose a unique credential name and document it clearly if users or administrators are expected to configure the value themselves.

For production applications, it is recommended that you avoid using literal API key strings and instead use an environment variable or a value stored in the Windows Credential Manager. If you must provide the API key as a literal string, you should take additional steps to protect it, such as storing the key in an encrypted form and limiting access to authorized users or processes. Avoid embedding API keys directly in application source code, configuration files, installers or other content that could be exposed through version control systems, logs or public repositories.

This method will block the calling thread until the connection has been established or the timeout period has elapsed. The connection established by this method 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;
    }

    // Establish a connection to OpenAI using the default endpoint
    // and a lightweight model
    hClient = LlmConnect(
        LLM_PROVIDER_OPENAI,
        LLM_OPTION_DEFAULT,
        LLM_TIMEOUT,
        NULL,                  // Use default URL
        _T("gpt-5.4-nano"),    // Model name
        _T("%OPENAI_API_KEY%") // Environment variable name
    );

    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