Session Monitoring and Control (SMC)

This section contains the Application Programming Interface (API) for the Session Monitoring and Control. The Session Monitoring and Control APIs allow the user mode applications to obtain information about ICA sessions and/or exercise control over bandwidth used by ICA sessions.

The unit of measurement for all bandwidth readings is bits per sec.

Nomenclature

The following data types are assumed to be defined in the following sections:

• WCHAR, a 16 bit UNICODE character
• UINT32, a 32 bit unsigned integer
• UINT64, a 64 bit unsigned integer

Server functions

WFSmcGetVersionSupported

DWORD WINAPI WFSmcGetVersionSupported (

      IN HANDLE hServer

      OUT UINT32* pVersionSupported,

      OUT UINT32* pFeaturesSupported

);

Description:

Returns the SMC API version number and the features supported on the current server. This API is supported only on the current server.

Parameters:

Return values:

WFSmcGetServerData

DWORD WINAPI WFSmcGetServerData (

      IN HANDLE hServer,

      IN INT32 cbData,

      OUT PWFSMC_SERVER_DATA pData,

      IN UINT32 cbServerVCData,

      OUT PWFSMC_SERVER_VC_DATA pServerVCData,

      IN OUT UINT32 *pcVCs

);

Description:

Returns cumulative totals for the server. See the WFSMC_SERVER_DATA definition for details. This API is supported only on the current server.

Parameters:

Returns:

Session functions

WFSmcOpenSessionHandle

INT WINAPI WFSmcOpenSessionHandle(

      IN HANDLE hServer,

      IN UINT32 SessionId,

      OUT PHANDLE phSession

);

Description:

Returns a handle to the caller which uniquely identifies a session in the context of this API set.

Parameters: |Parameter|Description| |—|—| |hServer | A handle to a server that is running CVAD Server. Specify WF_CURRENT_SERVER_HANDLE touse the current server.| | SessionId| Session Id of the session for which the handle is required.| |phSession | Address of a HANDLE, which receives a handle to the session. This handle is valid in the context of this API set. When the caller has finished with this handle, it should be closed by a call to the WFSmcCloseSessionHandle function.|

Returns:

WFSmcCloseSessionHandle

INT WINAPI WFSmcCloseSessionHandle(

      IN HANDLE hServer,

      IN HANDLE hSession

);

Description:

Invalidates a session handle, which was obtained through a previous call to the WFSmcOpenSessionHandle function. After a handle is invalidated, calls to the other functions in the API set returns ERROR_INVALID_HANDLE. This function should be called when a handle is no longer required since it allows the DLL to internally release resources used by the handle.

Parameters:

Returns:

WFSmcGetSessionVirtualChannelNames

INT WINAPI

WFSmcGetSessionVirtualChannelNames (

      IN     HANDLE                       hServer,

      IN     HANDLE                       hSession,

      IN     UINT32                       cbSessionVCNames,

      OUT    PWF_SMC_SESSION_VC_NAME    pSessionVCNames,

      IN OUT UINT32*                     pcSessionVCNames

);

Description:

Returns the Virtual Channel names in use for a session. This API is supported only on the current server.

Parameters:

Returns:

Remarks

Set the VersionNumber data member of structure WF_SMC_SESSION_VC_NAME = SMC_STRUCTURE_VERSION_V1 before calling the API

WFSmcGetSessionData

INT WINAPI WFSmcGetSessionData (

      IN     HANDLE                       hServer,

      IN     HANDLE                       hSession,

      IN     UINT32                       cbData,

      OUT    PWF_SMC_SESSION_DATA   pData,

      IN     UINT32                       cbVCData,

      OUT    PWF_SMC_SESSION_VC_DATA       pVCData,

      IN OUT UINT32*                      pcVC

);

Description:

Returns the bandwidth usage, compression ratios and latency values for the session, as well as the bandwidth used by the virtual channels in the session if required. The bandwidth usage for the virtual channels is returned as an array of WFSmc_Session_VC_Data structs. Each entry in the array corresponds to the virtual channel returned by a call to the WFSmcGetSessionVirtualChannelNames function. This API is supported only on the current server.

Parameters:

Returns:

Remarks

Set the VersionNumber data member of structures WF_SMC_SESSION_VC_NAME & WF_SMC_SESSION_DATA = SMC_STRUCTURE_VERSION_V1 before calling the API

WFSmcGetSessionDataV2

INT WINAPI WFSmcGetSessionDataV2 (

      IN     HANDLE                       hServer,

      IN     HANDLE                       hSession,

      IN     UINT32                       cbData,

      OUT pCtx_Smc_Session_Data_V2 pData,

      IN     UINT32                       cbVCData,

      OUT pCtx_Smc_Session_VC_Data_V2 pVCData,

      IN OUT UINT32*                      pcVC

);

Description:

Returns the bandwidth usage, compression ratios and latency values for the session, as well as the bandwidth used by the virtual channels in the session if required. The bandwidth usage for the virtual channels is returned as an array of Ctx_Smc_Session_VC_Data_V2 structures. Each entry in the array corresponds to the virtual channel returned by a call to the WFSmcGetSessionVirtualChannelNames function. This API is supported only on the current server.

This api returns Ctx_Smc_Session_Data_V2 per connection. As per multistream ICA, we can have 4 connections per session.

Parameters:

Returns:

Remarks

Set the VersionNumber data member of structures CTX_SMC_SESSION_DATA_V2 & CTX_SMC_SESSION_VC_DATA_V2 = SMC_STRUCTURE_VERSION_V2 before calling the API

WFSmcGetSessionLatencyData

INT WINAPI WFSmcGetSessionLatencyData {

      IN  HANDLE   hServer,

      IN  HANDLE  hSession,

      OUT UINT32* pLastLatency,

      OUT UINT32* pAverageLatency,

      OUT UINT32* pRoundTripDeviation,

      OUT UINT32* pTickCountLastUpdateTime

);

Description:

Returns the latency information for a session, a NULL pointer for any of the UINT32 pointers is ignored. This API is supported only on the current server.

Parameters:

Returns:

Remarks:

Not all ICA sessions support gathering of latency information. Only those clients with a version number of 6.0.910 or later, support gathering of latency information. In addition, depending on the setting used on the client for mouse feedback, the latency information for some clients will take a longer time to become available than for other clients.

WFSmcGetSessionBandwidthLimits

INT WINAPI WFSmcGetSessionBandwidthLimits (

      IN  HANDLE hServer,

      IN  HANDLE  hSession,

      IN  UINT32  cEntries,

      IN  UINT32* pVCIDs,

      OUT UINT32* pVCLimits

);

Description:

Returns the bandwidth limit settings for a session. This API is supported only on the current server.

Parameters:

Returns:

Remarks:

The bandwidth limits for one or more VCs may be requested by the call. The cEntries specifies how many. The IDs must match the values obtained by a call to WFSmcGetSessionVirtualChannelNames() with the exception that an ID value of 0xFFFFFFFF specifies the bandwidth limit of the whole session.

WFSmcSetSessionBandwidthLimits

INT WINAPI WFSmcSetSessionBandwidthLimits (

      IN HANDLE  hServer,

      IN HANDLE  hSession,

      IN UINT32  cEntries,

      IN UINT32* pVCIDs,

      IN UINT32*  pVCLimits

);

Description:

Sets the bandwidth limits for a session. This API is supported only on the current server.

Parameters:

Returns:

Remarks:

The bandwidth limits for one or more VCs may be set by the call. The cEntries specifies how many. The IDs must match the values obtained by a call to WFSmcGetSessionVirtualChannelNames() with the exception that an ID value of 0xFFFFFFFF specifies the bandwidth limit of the whole session.

WFSmcGetSessionPriorities

INT WINAPI WFSmcGetSessionPriorities(

      IN  HANDLE  hServer,

      IN  HANDLE  hSession,

      IN  UINT32  cEntries,

      IN  UINT32* pVCIDs,

      OUT UINT32* pVCPriorities

);

Description:

Returns the VC priority settings for this session. This API is supported only on the current server.

Where,

Priorities are from the set

# define CTX_SESSION_VC_PRIORITY_HIGHEST 0

# define CTX_SESSION_VC_PRIORITY_HIGH 1

# define CTX_SESSION_VC_PRIORITY_NORMAL 2

# define CTX_SESSION_VC_PRIORITY_LOW 3
<!--NeedCopy-->

Parameters:

Returns:

Remarks

The priorities for one or more VCs may be requested by the call. The cEntries specifies how many. The IDs must match the values obtained by a call to WFSmcGetSessionVirtualChannelNames().

WFSmcSetSessionPriorities

INT WINAPI

WFSmcSetSessionPriorities(

      IN HANDLE  hServer,

      IN HANDLE hSession,

      IN UINT32  cEntries,

      IN UINT32*  pVCIDs,

      IN UINT32*  pVCPriorities

);

Description:

Sets the VC priority settings for this session. This API is supported only on the current server.

Where,Priorities are from the set

# define CTX_SESSION_VC_PRIORITY_HIGHEST 0

# define CTX_SESSION_VC_PRIORITY_HIGH 1

# define CTX_SESSION_VC_PRIORITY_NORMAL 2

# define CTX_SESSION_VC_PRIORITY_LOW 3
<!--NeedCopy-->

Parameters:

Returns:

Required compatibility

SMC_API_COMPATIBILITY_XPE_FR1

Remarks:

The priorities for one or more VCs may be set by the call. The cEntries specifies how many. The IDs must match the values obtained by a call to WFSmcGetSessionVirtualChannelNames().