Skip to content

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

Parameter Description
[In] sessionId ICA session ID (or LF_CURRENT_SESSION)
[In] pVirtualName Pointer to virtual channel name
[Out] pHandle Pointer to virtual channel handle

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

Parameter Description
[In] handle Virtual channel handle previously returned by LFVirtualChannelOpen
[In] pBuffer Pointer to buffer that receives the data to read
[In] length Length of the data to read (bytes)
[Out] pBytesRead Returns the amount of data that has been read

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

Parameter Description
[In] handle Virtual channel handle previously returned by LFVirtualChannelOpen
[In] pBuffer Pointer to buffer containing the data to write
[In] length Length of the data to write (bytes)
[Out] pBytesWritten Returns the amount of data that has been written

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

Parameter Description
[In] handle Virtual channel handle previously returned by LFVirtualChannelOpen.
[In] virtualClass The type of information requested (LF_VIRTUAL_CLASS).
[Out] ppBuffer Pointer to a buffer pointer, which is allocated upon successful return. After a successful return, the caller is responsible for deallocating the buffer returned.
[Out]pBytesReturned Pointer to a size_t that is updated with the length of the data returned in the allocated buffer upon successful return.

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

Parameter Description
[In] handle Virtual channel handle previously returned by LFVirtualChannelOpen

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

Parameter Description
[In] handle Virtual channel handle previously returned by LFVirtualChannelOpen

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

Parameter Description
[In] handle Virtual channel handle previously returned by LFVirtualChannelOpen

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

Parameter Description
[Out] pHandle Pointer to a session event handle.

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

Parameter Description
[Out] pHandle Pointer to the session event handle returned by LFSessionEventInit
[In/Out] pSessionId Pointer to a specific session ID or LF_ALL_SESSION
[In/Out] pEventMask Pointer to subscribed session events/Pointer to session events when subscribed session events happen
[In] timeoutMs Wait timeout in milliseconds

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

Parameter Description
[In] pHandle Pointer to the session event handle previously returned by LFSessionEventInit.

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

Was this article helpful?