Seamless Application Programming Guide by mui27967


									Seamless Application Programming Guide 
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:

Some portions of this document may require understanding of basic Windows programming
such as window creation, Windows messages, events, and Application Programming Interfaces

The following MSDN Web page provides many useful articles on windows and windowing:

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.

    Window became a visible window (including after window creation)
    WIN32 API: CreateWindow(Ex), ShowWindow

    Window was destroyed
    WIN32 API: DestroyWindow

    Window was put in the foreground
    WIN32 API: SetForegroundWindow, SetActiveWindow

    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:

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:


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

Note: These messages can be enabled by setting the seamless flag FORCE RAW MOUSE

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

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

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:

Note: These messages can be disabled by setting the following seamless flags:


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.


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.

ShowWindow( hWnd, SW_RESTORE)

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.

To top