SmartAuditor Event API Overview-1

SmartAuditor Event API Overview SmartAuditor provides the ability to record ICA sessions. The purpose of the SmartAuditor Event API is to allow third parties to augment session recordings with application specific event data. Arbitrary data can be added to the SmartAuditor recording stream in real-time during recording, and the same data can be retrieved in real-time during playback. Basic Concept The SmartAuditor Agent provides a simple COM interface that third party applications can use to add application specific event data into the recorded session. Session Recording SmartAuditor Event Data during recording Citrix Presentation Server Third Party Published Application SmartAuditor Agent LogData IUserAPI Published Application being recorded SmartAuditor Event API Event Data Recorded Stream Storage The above diagram shows a published application running on Presentation Server with SmartAuditor session recording enabled. During the lifetime of the recorded session, the published application can add application specific event data into the recorded stream using the LogData function provided by the IUserApi interface. Application specific event data are time stamped as they are added into the recorded stream. The same event data will be available during playback of the recorded session, synchronized with the playback stream in real-time. Session Playback The above diagram shows how application event data are consumed during session playback. Event data are displayed in the Events and Bookmarks panel of the SmartAuditor Player. The Player can also deliver the event data as recorded to a third party consumer application built using the Player SDK. The delivery of event data is synchronized with the playback in real-time. SmartAuditor Event API COM Server The SmartAuditor Event API is provided as a COM Server hosted by the SmartAuditor Agent, installed on each computer running Presentation Server with SmartAuditor enabled. The SmartAuditor Event API can be enabled or disabled on a per-server basis. The default setting for each SmartAuditor Agent installation is for the COM interface to be disabled. Any attempts to connect to the interface will fail until it is enabled by the Presentation Server administrator. Please refer to the SmartAuditor Administrator’s Guide for more information on configuring the SmartAuditor Agent. When the SmartAuditor Event API is enabled, a COM interface called IUserApi is made available for third party applications to add event data to the recorded stream. The IUserApi interface contains only one function called LogData. Event Data Storage Event data is stored in the data stream within the session recording. If the searchable flag is set when the data is added to the recording stream, a database entry will be created and indexed against the fully qualified type associated with the data. As there is some overhead in storing each searchable event, this flag should only be set if there is an intention to search on the event text. See CTX114748 - Citrix SmartAuditor Database Schema for more information on the database storage. SmartAuditor Event Data Playback Event data added to SmartAuditor recording files are automatically available during playback. Event data are organized in a similar manner as bookmarks, and are listed in the Events and Bookmarks panel of the SmartAuditor Player. The following screenshot shows the event data as seen in the Events and Bookmarks panel (lower left corner) of the SmartAuditor Player: Event items are labelled with a yellow dot, both in the Events and Bookmarks panel and on the player window timeline bar. Note that only the event text is displayed in the SmartAuditor Player; event binary data can only be retrieved through custom applications built on the SmartAuditor Player SDK (see the next section for more details.) Recordings containing event data originally recorded with the searchable flag set can be found using the SmartAuditor Player’s advanced search form as shown below. This allows searching by both event text and event type name.
SmartAuditor Player SDK As indicated in the previous section, text associated with event data are automatically made available during playback within the SmartAuditor Player. Event data can also be accessed during playback via a set of library functions provided by the SmartAuditor Player SDK. The use of the Player SDK is optional. Its primary use is the rendering binary data associated with each event during playback. The Player SDK is based on an event notification or callback interface, where a third party application registers an event handler where event data can be delivered in real-time during session playback. The following C++ code fragment illustrates a typical lifecycle of an application making use of the SmartAuditor Player SDK: // initialize Player SDK CtxPlay_Initialize(); // register event handler for all event type CtxPlay_RegisterEventHandler(MyEventHandler, L "/"); // wait for event processing is completed (ie. via the CtxPlay_Abort() call) CtxPlay_WaitForCompletion(); // clean up CtxPlay_Dispose(); Note that the code fragment assumes that a callback function MyEventHandler is defined elsewhere. MyEventHandler is responsible for receiving event data and perform any processing as appropriate, for example, rendering event data in a human readable form. SmartAuditor Event API COM Server The SmartAuditor Event API is provided as a COM Server hosted by the SmartAuditor Agent, installed on each computer running Presentation Server with SmartAuditor enabled. When the SmartAuditor Event API is enabled, a COM interface called IUserApi is made available for third party applications to add event data to the recorded stream. The IUserApi interface contains only one function called LogData. ProgID The ProgID for the SmartAuditor Agent COM server is Citrix.SmartAuditor.Agent.UserApi. The ProgID is used to locate and instantiate the COM objects within the third party application. LogData The LogData function will record provided event data into the recorded session file associated with the Presentation Server / Terminal Services session ID specified. All parameters are validated for length and format before data is recorded. If the supplied session ID is not a current Terminal Services session, or the supplied session is not being recorded by the SmartAuditor Agent, then the function call will be ignored and no error will be returned to the caller. This is to prevent the Event API being used as a means for detecting whether a particular session is actually being recorded. The fully qualified type name associated with the event data is of the form typePart1.typePart2.typePart3. The type parts can be any string, but general good naming practise is CompanyName.Subsystem.Type. For example, AcmeInc.TradingApp.Transaction. interface IUserApi : IDispatch { HRESULT LogData( [in] int sessionId, [in] BSTR typePart1, [in] BSTR typePart2, [in] BSTR typePart3, [in] BSTR text, [in] SAFEARRAY(byte)/ data, [in] byte searchable); }; Parameters sessionId ID of Presentation Server / Terminal Services session to log event data for. The session ID must be greater than or equal to 0. Logging data for unknown session IDs will simply be ignored (that is, no exception will be thrown). typePart1 Event type first part of the fully qualified type name. Length of each part must be between 1 and 32 characters and must not contain any “.” (dot) characters. typePart2 Event type second part of the fully qualified type name. Length of each part must be between 1 and 32 characters and must not contain any “.” (dot) characters. typePart3 Event type third (and final) part of the fully qualified type name. Length of each part must be between 1 and 32 characters and must not contain any “.” (dot) characters. text Event text data. Length of string must be between 1 and 128 characters. data Event binary data. Length must be between 0 and 4096 bytes. searchable Flag indicating whether the text value is database searchable. If this flag is non-zero, a database entry indexed against the fully qualified type and text fields will be created in the SmartAuditor database for the event item. Return Values ERROR_SUCCESS (HRESULT value 0x00000000) if successful. If an invalid parameter value is detected, E_INVALIDARG (HRESULT value 0x8007057) is returned or if called from .NET managed code, a System.ArgumentException is thrown. Requirements Library Interface DLL Interop.UserApi.idl Requires Interop.UserApi.dll

SmartAuditor Player SDK CtxPlay_Initialize CtxPlay_Initialize is the initialization function which is called once to initialize the Player SDK. BOOL stdcall CtxPlay_Initialize() Parameters None Return Values The BOOL return value indicates whether the Player SDK initialization was successful. Requirements Header Library DLL See Also CtxPlay_UnregisterEventHandler Declared in CtxPlaySDK.h Link to CtxPlaySDK.lib Requires CtxPlaySDK.dll CTXPLAY_EVENT_CALLBACK CTXPLAY_EVENT_CALLBACK is the prototype of the callback function used in CtxPlay_RegisterEventHandler. typedef void (stdcall / CTXPLAY_EVENT_CALLBACK) ( IN CONST WCHAR/ eventType, IN CONST WCHAR/ label, IN CONST BYTE/ data, IN DWORD dataLength, IN SYSTEMTIME frameTimeUtc, IN SYSTEMTIME frameTime ); Parameters eventType [in] Type of event this data was registered against. label [in] Unicode text identifying this event. data [in] Event data. dataLength [in] Count of bytes of the data parameter. frameTimeUtc [in] Time in UTC when this event occurred. frameTime [in] Time in the server local time when this event occurred. Requirements Header Library DLL See Also CtxPlay_RegisterEventHandler Declared in CtxPlaySDK.h Link to CtxPlaySDK.lib Requires CtxPlaySDK.dll CtxPlay_RegisterEventHandler The CtxPlay_RegisterEventHandler function is used for registering a callback handler with the Player SDK. The callback handler receives events during the course of playback. BOOL stdcall CtxPlay_RegisterEventHandler ( CTXPLAY_EVENT_CALLBACK handler, CONST WCHAR/ eventTypeFilter ); Parameters Handler The function that will be called upon an event being received from the SmartAuditor Player. eventTypeFilter A string identifying the type of events to receive notifications for. If a handler is registered as L"/" then the handler will receive all events. Return Values The BOOL return value indicates whether the registration of the handler was successful. Requirements Header Library DLL See Also CtxPlay_UnregisterEventHandler Declared in CtxPlaySDK.h Link to CtxPlaySDK.lib Requires CtxPlaySDK.dll CtxPlay_WaitForCompletion The CtxPlay_WaitForCompletion function waits for the completion of the event data processing or until CtxPlay_Abort is called. While event processing remains active, this routine will block. void stdcall CtxPlay_WaitForCompletion() Parameters None Return Values None Requirements Header Library DLL See Also CtxPlay_Abort Declared in CtxPlaySDK.h Link to CtxPlaySDK.lib Requires CtxPlaySDK.dll CtxPlay_UnregisterAllEventHandlers The CtxPlay_UnregisterAllEventHandlers function un-registers all event handlers previously registered with CtxPlay_RegisterEventHandler. void stdcall CtxPlay_UnregisterAllEventHandlers() Parameters None Return Values None Requirements Header Library DLL See Also CtxPlay_RegisterEventHandler Declared in CtxPlaySDK.h Link to CtxPlaySDK.lib Requires CtxPlaySDK.dll CtxPlay_Dispose The CtxPlay_Dispose function releases any resources that the Player SDK may have consumed. void stdcall CtxPlay_Dispose() Parameters None Return Values None Requirements Header Library DLL See Also CtxPlay_Initialize Declared in CtxPlaySDK.h Link to CtxPlaySDK.lib Requires CtxPlaySDK.dll CtxPlay_Abort The CtxPlay_Abort function aborts the processing of events. void __stdcall CtxPlay_Abort() Parameters None Return Values None Requirements Header Library DLL Declared in CtxPlaySDK.h Link to CtxPlaySDK.lib Requires CtxPlaySDK.dll See Also CtxPlay_Initialize, CtxPlay_WaitForCompletion Code Samples Listed below are some code samples for logging and retrieving event data. Since the SmartAuditor Event API is implemented as a COM server, many programming languages are capable of being used as clients for logging event data. The code samples require the SmartAuditor Event API and Player SDK, which is available for download from the Citrix Developer Network http://support.citrix.com/. Adding Event Data to Recorded Session C/# In order to make use of the SmartAuditor Event API COM interface, you will need a .NET callable wrapper called Interop.UserApi.dll. You can find this DLL in the SmartAuditor Agent installation directory. The following code sample assumes that SmartAuditor Interop.UserApi.dll has been added as a reference in the C/# project. using System; using System.Diagnostics; using System.Runtime.InteropServices; using Interop.UserApi; // Interop derived from IUserApi.idl namespace UserApiSample { ///

/// Class for logging SmartAuditor Event Data ///

public class EventDataLogger { ///

/// ProgID for SmartAuditor Event API ///

private const string EventApiProgID = "Citrix.SmartAuditor.Agent.UserApi"; ///

/// COM interface for calling the SmartAuditor Event API ///

private IUserApi m_EventApi = null; ///

/// Log event data for specified Terminal Services session ///

/// Terminal Services session ID /// part 1 of event data type /// part 2 of event data type /// part 3 of event data type /// event text data /// event binary data /// indicate whether text data is searchable public void LogData( int sessionId, string dataType1, string dataType2, string dataType3, string textData, byte[] binaryData, bool searchable) { try { if (null == m_EventApi) { // create instance of Event API COM object Type type = Type.GetTypeFromProgID(EventApiProgID, true); if (null != type) { object obj = Activator.CreateInstance(type); m_EventApi = (IUserApi)obj; } } if (null != m_EventApi) { m_EventApi.LogData( sessionId, dataType1, dataType2, dataType3, textData, ref binaryData, Convert.ToByte(searchable) ); } else { Debug.WriteLine("Uninitialized Event API object"); throw new InvalidComObjectException("Uninitialized Event API object"); } } catch (System.Exception ex) { Debug.WriteLine(ex.Message); throw ex; } } } } The following code fragment illustrates how to obtain the Terminal Session ID for the current application. Please refer to Microsoft Platform SDK documentation for more information on Terminal Services related functions. ///

/// Enum for TS session information ///

public enum WTS_INFO_CLASS { WTSInitialProgram, WTSApplicationName, WTSWorkingDirectory, WTSOEMId, WTSSessionId, WTSUserName, WTSWinStationName, WTSDomainName, WTSConnectState, WTSClientBuildNumber, WTSClientName, WTSClientDirectory, WTSClientProductId, WTSClientHardwareId, WTSClientAddress, WTSClientDisplay, WTSClientProtocolType } ///

/// ID for querying current TS session ///

public const int WTS_CURRENT_SESSION = -1; ///

/// pinvoke for WTSQuerySessionInformation ///

[DllImport("Wtsapi32.dll")] public static extern bool WTSQuerySessionInformation( System.IntPtr hServer, int sessionId, WTS_INFO_CLASS wtsInfoClass, out System.IntPtr ppBuffer, out uint pBytesReturned); ///

/// Get the current TS session ID ///

public int GetCurrentSessionID() { int sessionID = -1; uint bytesReturned = 0; System.IntPtr buffer = IntPtr.Zero; bool retCode = WTSQuerySessionInformation( System.IntPtr.Zero, WTS_CURRENT_SESSION, WTS_INFO_CLASS.WTSSessionId, out buffer, out bytesReturned); if (retCode) { sessionID = Marshal.ReadInt32(buffer); } return sessionID; } The following code fragment illustrates how event data is added to the session recording. The application is assumed to be running as a published application, and the ICA session is currently being recorded. Note that no error will be generated if the ICA session is not being recorded; this is a security feature of the EventAPI to prevent users from determining if session recording is in effect. try { // get the current Terminal Services session ID int sessionID = GetCurrentSessionID(); // create EventDataLogger instance EventDataLogger eventLogger = new EventDataLogger(); // log some event data eventLogger.LogData( sessionID, "AcmeInc", "TransactApp", "Transaction", "Order /#123 completed", new byte[0], true); } catch (System.Exception ex) { Debug.WriteLine(ex.Message); throw ex; }

Adding Event Data to Recorded Session VB.Net In order to make use of the SmartAuditor Event API COM interface, you will need a .NET callable wrapper called Interop.UserApi.dll. You can find this DLL in the SmartAuditor Agent installation directory. The following code fragment assumes that SmartAuditor Interop.UserApi.dll has been added as a reference in the VB.Net project. Imports System.Runtime.InteropServices ' Sub routine for logging event data Sub LogData( ByVal sessionId As Int32, ByVal text As String, ByVal bytes As Byte(), ByVal searchable As Byte) Dim eventApi As IUserApi = CType(CreateObject("Citrix.SmartAuditor.Agent.UserApi"), IUserApi) eventApi.LogData( sessionId, "AcmeInc", "TransactApp", "Transaction", textLabel.Text, bytes, searchable) End Sub

Retrieving Event Data during Session Playback C++ The following code fragment illustrates a typical use of the SmartAuditor Player SDK to receive event data during session playback. Note that the /#include statement assumes that the SmartAuditor Player SDK is installed and available. This code uses the .NET extension to C++. Using namespace System; /#include "CtxPlaySDK.h" /// / Handle binary event data // void HandleBinaryData(const BYTE/ data, int dataLength) { // handle binary data as appropriate... } /// / Event data handler // void __stdcall MyEventHandler( IN CONST WCHAR/ eventType, // type of event IN CONST WCHAR/ label, // event text data IN CONST BYTE/ data, // event binary data IN DWORD dataLength, // length of binary data IN SYSTEMTIME frameTimeUtc, // event time in UTC IN SYSTEMTIME frameTime) // event time in server local time { // display event information Console::WriteLine(L"Event Received:"); String^ typeString = gcnew String(eventType); Console::WriteLine(L" Type: {0}", typeString); String^ labelString = gcnew String(label); Console::WriteLine(L" Label: {0}", labelString); // display event time Console::WriteLine(L" Time (UTC): {0}/{1}/{2} {3}:{4:d2}:{5:d2}", frameTimeUtc.wDay, frameTimeUtc.wMonth, frameTimeUtc.wYear, frameTimeUtc.wHour, frameTimeUtc.wMinute, frameTimeUtc.wSecond); Console::WriteLine(L" Time (Local): {0}/{1}/{2} {3}:{4:d2}:{5:d2}", frameTime.wDay, frameTime.wMonth, frameTime.wYear, frameTime.wHour, frameTime.wMinute, frameTime.wSecond); // display binary data information Console::WriteLine(L" Data ({0} bytes):", dataLength); // handle binary data HandleBinaryData(data, dataLength); Console::WriteLine(L"---------------------------------------------------\n"); } /// / sample main // int main(array ^args) { const wchar_t/ eventTypeFilter = L"/"; // initialize and register an event handler for the event type filter specified CtxPlay_Initialize(); CtxPlay_RegisterEventHandler(MyEventHandler, eventTypeFilter); // wait for event data processing to complete or CtxPlay_Abort() CtxPlay_WaitForCompletion(); // clean up CtxPlay_Dispose(); Console::WriteLine(L"\nEvent data processing completed."); return 0; }