Seamless Application Programming Guide Goal The purpose of this document is to provide best practices from an application developer's perspective on the common nuances encountered with application development for troubleshooting application issues in a seamless Citrix environment. Target Audience Application developers, Citrix server administrators, and help desk personnel. Please note that the topic of application compatibility specific to a Terminal Services environment is outside the scope of this document. Please refer to the following Microsoft article for more information: http://msdn2.microsoft.com/en-us/library/Aa383490.aspx Some portions of this document may require understanding of basic Windows programming such as window creation, Windows messages, events, and Application Programming Interfaces (APIs). The following MSDN Web page provides many useful articles on windows and windowing: http://msdn2.microsoft.com/en-us/library/ms632595.aspx Background This section lists the specific aspects of the seamless architecture. In Figure 1 below, there is a consistent communication flow in both directions between application windows and the seamless subsystem. Incoming information to application windows arrive in the form of Windows messages and APIs. Outgoing messages are initiated from a Microsoft Active Accessibility Hook and sent to the seamless subsystem through a memory- mapped file and events. Figure 1: Top-level windows: The seamless subsystem only interacts with top-level windows and not with other types of windows, such as Multiple-document Interface (MDI) child windows and toolbar icons. Typically, it interacts with top-level windows that are enumerated with the WIN32 API, EnumWindows, and not the type that do not have a parent/owner. Active accessibility hook: The seamless subsystem makes use of the Microsoft Active Accessibility feature. Whenever one of the following events occur in an application’s top-level window, the seamless subsystem receives a notification. • EVENT_OBJECT_SHOW Window became a visible window (including after window creation) WIN32 API: CreateWindow(Ex), ShowWindow • EVENT_OBJECT_DESTROY Window was destroyed WIN32 API: DestroyWindow • EVENT_SYSTEM_FOREGROUND Window was put in the foreground WIN32 API: SetForegroundWindow, SetActiveWindow • EVENT_OBJECT_LOCATIONCHANGE Window size or position has changed WIN32 API: MoveWindow, SetWindowPos Minimizing the number of these events improves the server’s scalability as well as overall application performance. For more information on Active Accessibility, see the following Microsoft article: http://msdn2.microsoft.com/en-us/library/ms697240.aspx Absence of Windows shell: ICA seamless, ICA windowed, and RDP "Starting Program" sessions are all Terminal Services desktop sessions without the presence of the Windows Start menu and Windows desktop shell. Under any of these types of sessions, most applications are able to operate without any issues. However, some applications may encounter a problem where they may make specific API calls or have dependencies on the Windows shell in some part. For example, some advanced shell interfaces that directly manipulate the Explorer shell GUI are not supported and may change appearance in a seamless session (for example, the lack of a Taskbar icon). Here are some examples: ITaskbarList http://msdn2.microsoft.com/en-us/library/ms631840.aspx ITaskbarList2 http://msdn2.microsoft.com/en-us/library/ms631834.aspx The seamless subsystem has limited shell support. Elements of the limited shell feature support consist of the following: 1. Shell_NotifyIcon 2. SHAppBarMessage (Note: This API is currently not fully supported) 3. Windows that support shell features usually created by the Explorer desktop For example: Window text Window class Parent "" Shell_TrayWnd None "" TrayNotifyWnd Shell_TrayWnd "Program Manager" Progman None How mouse messages are posted: Moving or resizing a window does not generate any WM_MOUSEMOVE messages to be posted to an application. This behavior occurs by design to cache those messages and improve performance. Note: These messages can be enabled by setting the seamless flag FORCE RAW MOUSE EVENTS TO SERVER Windows styles: A window that has a style equal to WS_POPUP, WS_VISIBLE and WS_CLIPSIBLINGS, is by default treated as a balloon pop-up and the seamless client subsystem will set its parent to its own hidden window. This may cause problems in window relationships as well as taskbar icon appearance. Identifying the correct behavior of an application Running applications in a seamless Citrix environment may expose specific issues with an application itself that are not normally seen when running the same application on a workstation. There are several factors that may contribute to the difference in behavior. Windows messages: There are several Windows messages listed below that are used by the seamless subsystem that applications may not be used to receiving as frequently as when they are run in a seamless session. Issues may arise when an application does not process these messages correctly. This results in the application appearing to behave differently when run in a seamless session. For example, if an application uses a memory allocation routine for the WM_GETICON event without any corresponding free memory routine, the application may start using a large amount of memory. This could lead to application errors or application crashes. The following messages are sent on a frequent basis to application windows to get the associated icons: WM_QUERYDRAGICON WM_GETICON (ICON_BIG and ICON_SMALL) Note: These messages can be disabled by setting the following seamless flags: SEND NO ICON CHANGES DISABLE WM_QUERYDRAGICON MESSAGES The following messages may be posted when certain conditions are met: WM_NULL – used to check if the target window is responding. WM_CANCELMODE – used in certain conditions where a call to SetForegroundWindow fails. APIs: Below are several Windows APIs used by the seamless subsystem that applications may not be used to receiving from other processes. Issues may arise when an application does not respond correctly to these APIs. This results in the application appearing to behave differently when run in a seamless session. MoveWindow SetWindowPlacement SetForegroundWindow ShowWindow( hWnd, SW_RESTORE) SetWindowPos More Information Citrix Knowledge Center article CTX101644 references specific settings called seamless flags, which can be used to modify certain application behavior when applications are run in a seamless session.
Pages to are hidden for
"Seamless Application Programming Guide"Please download to view full document