Mobile SDK for Windows Apps2.0
Transforming Windows apps into Mobile apps
Concepts

Mobile Device Challenges

Before diving into the specifics of the API, it is useful to understand the User Experience challenges for delivering legacy Windows applications via XenApp. In general, XenApp was designed to host legacy Windows applications and access these via Citrix Receiver on a wide range of client devices- typically Windows desktops and Laptops. In the new world of tablets and smarthphones, one can also access these same Windows applications on mobile devices. Citrix has done a lot of work on the Receiver to fine tune the user experience on the client side for mobile devices. In many ways, Citrix and XenApp provide the ideal platform for delivering Windows applications to mobile devices, in a secure way.

With the Citrix Mobile SDK for Windows Apps, developers can write XenApp hosted mobile friendly applications such that take the user experience to the next level, and similar to that of a native application on the mobile device. The next few sections will outline the areas of device functionality that are made available to a mobile friendly application via the SDK.

Buttons

The mobile device has a few buttons available. Typically an Apple phone or tablet has one button to control the application. An Android device can have four or more. Here is an example button list for Android:

  • Home
  • Back
  • Menu
  • Search

An application will want to know when certain buttons are pressed. For example, in a page hierarchy, the application will want to be back one level when Back is pressed. This functionality will be made available via the SDK API.

Feature Capabilities

As part of the negotiation between the server and the mobile device, a number of feature capabilities are determined to be common between both sides. If either side does not support a particular feature, it will not be used. The collection of common feature capabilities reveal what is available for the program to utilize.

Normally the virtual channel data related to feature capabilities is not exposed to programs. However, for the sake of better support of the mobile device hardware, the API includes functions to gather capability information. For example, the feature capabilities reveal whether or not a camera is in the device. The feature capabilities also describe the display settings.

Capabilities is similar to having an inventory of features. However, it is different in that it can classify more than just feature sets. It can also include default settings and whether or not a set of functions is supported at all.

Audio

Capture (record) audio from remote locations and store in data centre.

Version 2 of the SDK adds the ability to capture audio from the connected device. The user selects the moment to capture the audio. The audio is then processed and the filename sent back to the program. The program then uses standard file access over Client Drive Mapping (CDM). If the device does not have storage enabled or access has not been given to Citrix Receiver, the request to capture audio will fail.

Camera

Capture pictures from remote locations and store in data centre.

Version 1 of the SDK focused on providing the most common use case for taking pictures. The application requests a picture. The user selects the moment to take the picture. The picture is then processed and the filename sent back to the program. The program then uses standard file access over Client Drive Mapping (CDM). If the device does not have storage enabled or access has not been given to Citrix Receiver, the request to take a picture will fail.

Version 2 of the SDK adds enhanced support for capturing media from the connected device. This include enhancements to capture picture, as well as the ability to capture video.

Customization for Mobile Device

If an application is aware of the characteristics of the mobile device, it can then leverage this information to significantly improve the user experience. It is important for the application developer to infuse the look and feel of the native mobile platform and follow the rules of the UI guidelines for that platform.

The easiest way to handle this is to determine the device type using the capabilities API and then using a framework (like WPF) that supports having different skins for the application.

Display

The mobile device displays are more advanced than typical PC displays. Most mobile displays support multi-touch with a higher pixel density. Windows applications need to be adjusted to correctly display on these smaller but usually higher Pixel-Per-Inch (PPI) screens. With the SDK, display metrics are retrieved and change notification events are made available to the application. The application is made aware of the device resolution and the pixel density. Using this information the application can ensure that Text is easy to read, buttons widgets are big enough to touch, etc. Layouts can also be re-arranged to fit on the screen, whether it is a smartphone or a tablet form factor.

Events

Events notify the program of activity and state changes for the CMP object. Some API are asynchronous and require events for completion notification. For example, a SetOrientation request will trigger an OrientationChanged event later on. The program can only determine the orientation state by either using a GetOrientation or hooking the OrientationChanged event.

Hooking events is the right way to get notified of changes. Otherwise it would be necessary to poll the API for changes and this is not as efficient.

Using events is very much like handling Windows messages. The handler takes at least one parameter and the value determines what has changed.

CMP_EVENT_APP_BACKGROUNDAppBackground
CMP_EVENT_APP_FOREGROUNDAppForeground
CMP_EVENT_AUDIO_CAPTUREDAudioCaptured
CMP_EVENT_BUTTON_PRESSEDButtonPressed
CMP_EVENT_BUTTON_TARGET_CHANGEDButtonTargetChanged
CMP_EVENT_CAMERA_PICTURE_REMOVEDPictureRemoved
CMP_EVENT_CAMERA_PICTURE_TAKENPictureTaken
CMP_EVENT_CAPTURE_MEDIA_REMOVEDCaptureMediaRemoved
CMP_EVENT_CHANNEL_STATE_CHANGEDChannelStateChanged
CMP_EVENT_CONTROL_STATE_CHANGEDControlStateChanged
CMP_EVENT_DISPLAY_SETTINGS_CHANGEDDisplaySettingsChanged
CMP_EVENT_FOREGROUND_APP_CHANGEDForegroundAppChanged
CMP_EVENT_KEYBOARD_STATE_CHANGEDKeyboardStateChanged
CMP_EVENT_ORIENTATION_CHANGEDOrientationChanged
CMP_EVENT_PHONE_CALL_STARTEDPhoneCallStarted
CMP_EVENT_PICKER_CONTROL_STATE_CHANGEDPickerControlStateChanged
CMP_EVENT_PICTURE_CAPTUREDPictureCaptured
CMP_EVENT_SCROLL_MODE_CHANGEDScrollModeChanged
CMP_EVENT_SESSION_STATE_CHANGEDSessionStateChanged
CMP_EVENT_SMS_STARTEDSMSStarted
CMP_EVENT_SUPPORTED_ORIENTATIONS_CHANGEDSupportedOrientationsChanged
CMP_EVENT_USER_NOTIFIEDUserNotified
CMP_EVENT_VIDEO_CAPTUREDVideoCaptured
CMP_EVENT_VIEWPORT_CHANGEDViewportChanged
CMP_EVENT_VIEWPORT_ORIGIN_CHANGED

ViewportOriginChanged

Keyboard

In general, mobile devices typically do not have physical keyboards and the only keyboard is an on-screen keyboard (OSK). Existing Windows applications assume that a physical keyboard is always available. So, there are two basic problems for hosted legacy applications being accessed via a mobile device. First, something needs to trigger the device OSK to appear and disappear. Secondly, the device OSK popup needs to be configured to show the right layout. The SDK will enable an application to decide when the device display keyboard should be present and the type of layout that is appropriate.

Location Services

Many mobile devices provide the ability for applications to retrieve the location of the device either in the form of latitude and longitude coordinates, or through geocoding, the address of the device. The Mobility Pack and Windows Location API provides the ability for Windows applications running in XenApp to utilise the location information of the device while in a Receiver session.

Orientation

There is rarely a concept of changing display orientation in a typical legacy Windows application. The PC-based devices (laptops and workstations) typically do not rotate the screen. Mobile devices (phone and tablet), on the other hand, have no need for a fixed orientation. It is perfectly fine to rotate a device in any direction and at any time. The user expects that the application will automatically adjust position and size. Sometimes applications are better suited for landscape or portrait. Currently there is support in Receiver to detect device orientation and then reposition and resize the session. A legacy Windows application can react to this change in session size if it chooses to do so. This is not always as effective in some scenarios. The delay between rotation and application change can at times be perceived as being laggy. The aim with SDK is that ensure that applications that are aware of orientation on XenApp can decide things for themselves; e.g lock orientation or change their layout.

Phone

The CMPStartCall API makes it possible to start phone calls based on contacts list on server. The user has the option of either allowing or cancelling the phone call. The phone number is not dialled without user interaction.

When the mobile device processes the request, it sends back an event to the server application. This event indicates whether or not the request was processed successfully.

Picker Control

The SDK API enables Citrix Native User Experience technology on the XenApp server to map a listbox in a legacy windows application to a local iPad/iPhone/Android Picker Control. Similarly a Scroll Bar in a legacy Windows application can be mapped to a Local Slider Control. An application developer can also make use of this functionality if they choose to do so.

PPI/DPI

PPI (Pixels Per Inch) and DPI (Dots Per Inch) are commonly used in computer display and printing terminology. The concept for both is essentially the same even though it is more accurate to use PPI when talking about computer displays.

One of the big differences between mobile devices and a typical computer display is that the mobile device can have a much higher PPI/DPI. This means that windows get smaller on mobile devices even though they could be the same resolution as a computer display.

This just means that the application has to re-adjust how it displays information. Typically, Windows programs are designed for 96 DPI. The iPhone 4 has 326 PPI. This is more than three times the pixel density of a default Windows application.

One software platform that makes it easier to adjust for different PPI is Windows Presentation Foundation (WPF).

It is important to determine mobile device DPI/PPI early in the application execution. Either the Capabilities or GetDisplaySettings can be used to find the current DPI/PPI.

Citrix Mobile Receiver Controls

The current Citrix Mobile Receivers like the Android Receiver have the following UI controls triggered by the user through a menu button:

  • Show Keyboard
  • Scrolling Mode
  • Close
  • Gestures Guide
  • Settings

A mobile friendly application may not require the user to use these controls in order to interact with it. Thus to maintain a native look and feel, the applications can hide the Receiver UI controls. In fact, some of them are going to want to override the behaviour of the buttons on the device. The SDK API addresses these requirements.

Return Status

The return code for most functions is CMPRESULT. CMPRESULT is defined as an INT32 (since it is used with COM automation) and is based on values from CMP_ERROR_ID enumeration. CMPRESULT is broken into two WORDs. The high word is for the component Id. The low word is for the status code. Only one status code (zero) indicates that there was no error. The rest of the codes indicate an error and these errors are specific to the component Id.

Error checking should happen with CMP_SUCCESS and CMP_FAILURE macros. A non-zero result could still be a success. Only the lower word should be checked for zero for success. The high word is the component that generated the result.

Scroll Mode

Typically, scrolling is easy on a mobile device. A single finger can move along the screen to indicate how fast to scroll in any direction for native applications. In contrast legacy Windows applications do not handle touch event natively. Touch support is new to Windows 7 and most programs do not use it directly. The result is that most Windows programs are based on the mouse and the scroll bar. The mousewheel is commonly used to scroll up and down. Windows typically emulates mouse events based on touch events. This gives the user a level of UX fidelity when using legacy apps with a touch screen. Receiver today does a translation of the touch events on the mobile device to windows message events. This is configurable using the UI control in Receiver through a setting called Scroll Modes. The modes result in the following translations:

  • Touch events to simulated mouse wheel events
  • Touch events to mouse drag events (simulated left mouse click and hold with mouse move)
  • Touch events to panning around viewport area (not mouse related). The SDK API will enable an application to programmatically change the scroll modes enforced by Receiver. The application ideally needs direct access to the touch events. If this is made possible then the application can control how the touch events are interpreted. This is planned to be made available in a future release of the SDK.

SMS

Send SMS from content on server. It is possible for the application to specify the phone number and the text for the message. However, both of these variables are optional.

UniqueId

There are many different requests that specify a UniqueId to help track the progress. For example, starting a phone call will trigger an event. That event will include the UniqueId specified by the function call. The UniqueId is an INT32 and is specified by the caller. It should be considered unique for the sake of identifying the original requests with responses and events.

Types of calls using UniqueId:

Viewport

One of the ideas to improve the User Experience is have a much higher XenApp session resolution and then let the user pan around the session on the smaller mobile device screen. With the SDK API an application can programmatically manipulate the Receiver viewport location.

 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Events Defines