Using APIs to Identify Remote Citrix/WTS Clients

Using APIs to Identify Remote Citrix/WTS Clients
Technical Note 1711
Last Reviewed 11-Nov-2004
Applies To
Reflection for IBM version 10.0 or higher
Reflection for HP version 10.0 or higher
Reflection for UNIX and OpenVMS version 10.0 or higher
Reflection for ReGIS Graphics version 10.0 or higher
Microsoft Windows 2000 Server with Terminal Services (with or without Citrix MetaFrame)
Microsoft Windows NT 4.0, Terminal Server Edition (with or without Citrix MetaFrame)
Summary

This technical note details how to use APIs to determine the remote IP address, Citrix username, or computer name of individual Citrix/Windows Terminal Server (WTS) clients in Citrix/WTS environments.

Why Obtain This Information?

When running in a Citrix/Windows Terminal Server (WTS) environment, users are not assigned individual IP addresses; instead, all users share the same IP address or group of IP addresses (in a Citrix farm).

In some situations, the system administrator may want to identify individual remote Citrix/WTS clients. For example, the administrator may want to assign remote computers to specific print queues based on the Citrix/WTS client's remote IP address, Citrix user name, or computer name.

In this instance, the administrator needs to determine the Citrix/WTS client's remote information. Once this information is obtained, the administrator can create a table that associates the remote client with the correct printer name. For example:

IP Address	Computer Name	Assigned Printer
129.23.30.49	SallyR	Printer_NYC
149.29.23.46	PetraK	Printer_Berlin

This table can be stored in a host program, a VBA script, or on the network, and must be updated any time the remote IP address or computer name changed.

The remote IP address, user name or computer name can be determined by using the API calls specified in the following section.

Note: In this scenario, the remote computers must be configured with unique, static IP addresses or computer names. Assigning a printer to individual IP addresses or computer names using a table is impractical if the remote computer is configured to dynamically obtain its IP address from DHCP, or if the computer is renamed frequently.

API Calls

Reflection version 10.0 or higher includes two API calls that can be used to determine the Citrix/WTS client's remote IP address or Citrix user name. Earlier versions of Reflection do not include these API's; however, there are two Citrix APIs that can be used to obtain remote IP addresses or computer name when using earlier versions of Reflection.

Reflection APIs

The following Reflection API calls can be used to determine the Citrix/WTS client's remote IP address or Citrix user name. These API calls can be used with the following Reflection 10.0 or higher products:

Reflection for HP with NS/VT
Reflection for UNIX and OpenVMS

Description	Environment	Reflection Call
Returns your IP address for connection to a Citrix host.	Citrix only	.CitrixIPAddress
Returns the user name value for a Citrix connection type.	Citrix or WTS	.CitrixUsername

Citrix APIs

The following Citrix API calls can be used to determine the Citrix/WTS client's remote IP address or computer name.

Description	Environment	Citrix/WTS API Call (in VB/VBA)
Returns the IP Address of the remote Citrix client machine.	Citrix only	CTXQuerySessionInformation("", WF_CURRENT_SESSION, WFClientAddress, ipAdress)
Obtains the computer name of the remote Citrix/WTS client machine.	Citrix WTS* * WTS returns the IP address of the remote machine as the computer name. In Citrix, the actual computer name is returned.	CTXQuerySessionInformation("", WF_CURRENT_SESSION, WFClientName, Computername)

Sample Scripts

The following three sample scripts provide examples of how to use the Reflection and Citrix API calls.

Using Reflection API Calls: CitrixIPAddress and CitrixUsername

The following sample script applies to the following Reflection products, version 10.0 or higher.

Reflection for HP with NS/VT
Reflection for UNIX and OpenVMS

The sample script It uses API calls, .CitrixIPAddress and .CitrixUsername, to determine the IP address and Citrix user name of the remote Citrix client machine. (Notes: .CitrixUsername can also be used with WTS.)

Sub get_Citirx_info_10_0_Reflection_RWIN_only()
   With Session
   MsgBox "Your citirx IP is <" & .CitrixIPAddress & _
   "> your Citrix logon name is " & _
   .CitrixUsername
   End With
End Sub

Using Citrix API Calls: WFClientAddress, ipAdress

The following sample script uses CTXQuerySessionInformation("", WF_CURRENT_SESSION, WFClientAddress, ipAdress) to obtains the remote computer's IP address and then transmits it to the host computer.

Sub TransmitClientIP()  ' Only called if you are on a Citrix Server.
  On Error GoTo ErrorHandler

  Dim LF As String    ' Chr$(rcLF) = Chr$(10) = Control-J
  Dim CR As String    ' Chr$(rcCR) = Chr$(13) = Control-M
  Dim ipAdress        As String ' Ip Address of ICA Client
  Dim svrHndl         As Long

  LF = Chr$(10)
  CR = Chr$(13)
  Dim svrHndl         As Long

  If CTXOpenServer(svrHndl, "") Then  ' Determine if Citrix is running.
    Call WFCloseServer(svrHndl)  ' If not running, close the Handle for
    ' Citrix and transmit IP address of the ICA client to the host
    ' machine.
    If CTXQuerySessionInformation("", WF_CURRENT_SESSION,
WFClientAddress, ipAdress) Then Session.TransmitANSI ipAdress

    End If
  Else
     Session.TransmitANSI "NO CITRIX IP" '
  End If
  Exit Sub
ErrorHandler:
' Note: This sample script contains no error handling.
' For error handling, create a log file or display an
' error message.

End Sub

Using Citrix API Calls: WFClientName, Computername

The following sample script uses CTXQuerySessionInformation("", WF_CURRENT_SESSION, WFClientName, Computername) to determine the computer name of the remote Citrix/WTS client machine.

' Returns the name of the remote computer via ICA Citrix
' Client API function. If you are running a MS RDP/Terminal
' Server Client connection, it returns the IP address of
' the client as the computer name, or if you are at the
' WTS/Citrix Console, it returns a "" Null string.

Function GetTheComputername() As String
On Error GoTo ErrorHandler

Dim LF As String    ' Chr$(rcLF) = Chr$(10) = Control-J
Dim CR As String    ' Chr$(rcCR) = Chr$(13) = Control-M
Dim Computername     As String ' Computer Name of ICA Client
Dim svrHndl          As Long

LF = Chr$(rcLF)
CR = Chr$(rcCR)
Dim svrHndl         As Long
  If CTXOpenServer(svrHndl, "") Then  ' See if Citrix is running.
    Call WFCloseServer(svrHndl)  ' If not, close the handle.
    ' Transmit the IP address of ICA client to host machine.
  If CTXQuerySessionInformation("", WF_CURRENT_SESSION,
WFClientName, Computername) Then
     GetTheComputername = Computername
     Exit Function
  End If
  End If
Exit Function

ErrorHandler:
' Note: This sample script contains no error handling.
' For error handling, create a log file or display an
' error message.

End Function

Additional Sample Scripts

The following sample scripts are available as support files on the Download Library at http://support.attachmate.com/downloads/.

Reflection for IBM

Name	Description
CitrixIBMAPI.ZIP	This file contains an example of Citrix API calls that can be used to get the IP address of a remote ICA Client and the computer name.

Reflection for HP

Name	Description
Cit90HP.r1w	This is a version 9.x settings file containing macros for Citrix API calls. It includes a macro to transmit the client IP address/computer name to the host.

Reflection for UNIX and OpenVMS (Formerly Reflection for UNIX and Digital)

Name	Description
host_vax_init_vba.txt	This DEC Command Language (DCL) file runs on a VAX system. It's a text file that runs a VBA Macro called TransmitClientIP. To run it on a VAX host, rename it to *.com. This sample script can be used with the Citrix API examples.

Reflection for ReGIS Graphics

Name	Description
Cit90rrg.r4w	This is a version 9.x settings file containing macros for Citrix API calls. It includes a macro to transmit the client IP address/computer name to the host.

VBA Scripts

Name	Description
Increment_AS400_citrix.zip	Use these files to automatically increment the AS/400 device name in a Citrix/WTS environment.
api_calls_citrix.r2w	Example of API calls that can be used to get the IP address of a Citrix ICA client.

1097	Index of Windows Terminal Server and Citrix XenApp Topics (Includes Citrix Presentation Server and MetaFrame)

Did this technical note answer your question?

Need further help? For technical support, please contact Support.

Technical Notes