Programming reference

The [In] and [Out] labels in the function calling conventions are for clarification only.

LFVirtualChannelOpen

This function is used to open a specified virtual channel.

Calling convention

CTX_STAT CTXAPI LFVirtualChannelOpen(
    uint32_t sessionId,
    const char* pVirtualName,
    VCHANDLE* pHandle);

 

Parameters

List of values for pSessionId:

# define LF_CURRENT_SESSION ((uint32_t)-1) /* current session ID used by both LFVirtualChannelOpen or LFWaitForSessionEvent */

 

Return value

The function returns:

• CTXSTAT_SUCCESS
• CTXSTAT_ERRORS

Remarks

1. A virtual channel name can contain a maximum of seven characters (excluding character ‘\0’).
2. Do not prefix a virtual channel name with CTX.

LFVirtualChannelRead

This function is used to read data from a specified virtual channel.

Calling convention

CTX_STAT CTXAPI LFVirtualChannelRead(
    VCHANDLE handle,
    void* pBuffer,
    size_t length,
    ssize_t* pBytesRead);

 

Parameters

Return value

The function returns:

• CTXSTAT_SUCCESS
• CTXSTAT_ERRORS

LFVirtualChannelWrite

This function is used to write data to a specified virtual channel.

Calling convention

CTX_STAT CTXAPI LFVirtualChannelWrite(
    VCHANDLE handle,
    const void* pBuffer,
    size_t length,
    ssize_t* pBytesWritten);

 

Parameters

Return value

The function returns:

• CTXSTAT_SUCCESS
• CTXSTAT_ERRORS

LFVirtualChannelQuery

This function is used to query data from a specified virtual channel.

Calling convention

CTX_STAT CTXAPI LFVirtualChannelQuery(
    VCHANDLE handle,
    LF_VIRTUAL_CLASS virtualClass,
    void** ppBuffer,
    size_t* pBytesReturned);

 

Parameters

List of values for virtualClass:

LFVirtualClientData /* virtual channel client module data (C2H data) */

 

Return value

The function returns:

• CTXSTAT_SUCCESS
• CTXSTAT_ERRORS

LFVirtualChannelPurgeInput

This function is used to purge all queued input data sent from the client to the server on a specific virtual channel.

Calling convention

CTX_STAT CTXAPI LFVirtualChannelPurgeInput(
    VCHANDLE handle);

 

Parameters

Return value

The function returns:

• CTXSTAT_SUCCESS
• CTXSTAT_ERRORS

LFVirtualChannelPurgeOutput

This function is used to purge all queued output data sent from the server to the client on a specific virtual channel.

Calling convention

CTX_STAT CTXAPI LFVirtualChannelPurgeOutput(
    VCHANDLE handle);

 

Parameters

Return value

The function returns:

• CTXSTAT_SUCCESS

• CTXSTAT_ERRORS

LFVirtualChannelClose

This function is used to close a specified virtual channel.

Calling convention

CTX_STAT CTXAPI LFVirtualChannelClose(
    VCHANDLE handle);

 

Parameters

Return value

The function returns:

• CTXSTAT_SUCCESS
• CTXSTAT_ERRORS

LFSessionEventInit

This function opens a handle for session event monitoring.

Calling convention

CTX_STAT CTXAPI LFSessionEventInit(
    EVTHANDLE* pHandle);

 

Parameters

Return value

• CTXSTAT_SUCCESS
• CTXSTAT_ERRORS

Remarks

Please run LFSessionEventInit at least once.

LFWaitForSessionEvent

This function subscribes to and waits for session events.

Calling convention

CTX_STAT CTXAPI LFWaitForSessionEvent(
    EVTHANDLE* pHandle,
    uint32_t* pSessionId,
    uint32_t* pEventMask,
    uint32_t timeoutMs);

 

Parameters

List of values for pSessionId:

# define LF_CURRENT_SESSION ((uint32_t)-1) /* current session ID used by both LFVirtualChannelOpen or LFWaitForSessionEvent */
# define LF_ALL_SESSION ((uint32_t)-2) /* only used by LFWaitForSessionEvent subcribe all session events /

 

List of session events for pEventMask:

# define WEVENT_DELETE 0x00000002 /* session delete */
# define WEVENT_CONNECT 0x00000008 /* session connect to client */
# define WEVENT_DISCONNECT 0x00000010 /* session disconnect from client */
# define WEVENT_LOGON 0x00000020 /* session logon */
# define WEVENT_LOGOFF 0x00000040 /* session logoff */
# define WEVENT_RECONNECT 0x00000800 /* session reconnect to client */

 

Return value

The function returns:

• CTXSTAT_SUCCESS
• CTXSTAT_ERRORS

Remarks

This LFWaitForSessionEvent function keeps blocking until the following conditions are met:

1. Subscribed session events happen when the return status shows CTXSTAT_SUCCESS.
2. CTXSTAT_ERRORS (including timeout).

LFSessionEventDestroy

This function closes the handle for session event monitoring.

Calling convention

CTX_STAT CTXAPI LFSessionEventDestroy(
    EVTHANDLE* pHandle);

 

Parameters

Return value

• CTXSTAT_SUCCESS
• CTXSTAT_ERRORS

All return values

CTXSTAT_SUCCESS = 0,
CTXSTAT_FAILURE = 1,
CTXSTAT_INVALID_PARAMETER = 2,
CTXSTAT_NOT_ENOUGH_MEMORY = 3,
CTXSTAT_DATA_ERROR = 4,
CTXSTAT_NOT_SUPPORTED = 5,
CTXSTAT_WINSTA_NO_SESSION = 6, /* no session running */
CTXSTAT_CHANNEL_NOT_BOUND = 7, /* fail to get virtual channel info from client */
CTXSTAT_CANTOPEN = 8,
CTXSTAT_TIMEOUT = 9,
CTXSTAT_VC_DISABLED = 10,
CTXSTAT_VC_DISCONNECTED = 11,
CTXSTAT_VC_ALREADY_IN_USE = 12