Citrix Blogger

XAMA SDK documentation is now available online at http://www.citrixcloud.net/mobilesdk/index.html. The documentation was generated from the source code using doxygen.  Because of this, the information is more up to date than typical SDK documents.  Three interfaces are covered.

1. C/C++ XAMA API
2. COM XAMA Interfaces
3. C# XAMA API

Since COM and .NET are supported, it actually means more languages would work besides C/C++/C#.  However, we have not tested other combinations.

Looking through the API online is the easiest way to get an idea of how the API are called.  For example, take a look at CMPTakePicture for C/C++.  Given this knowledge along with the takepicture sample, it would be possible to build a program that uses the camera pretty fast on XenApp.

As a side note, one of the interesting use cases is being able to transfer photos right after they are taken to the server.  The access is protected over the ICA link and the copy process uses client drive access.  In other words, it is fully under the control of the program how the picture data is copied once it is taken.  There are security and privacy concerns so some rules are in effect.  First, the user has to enable access to the SD card to Receiver.  Second, the administrator has to enable transferring data with CDM (Client Drive Mapping).  Third, the user selects when the picture is taken manually.  The server cannot say when the actual picture is taken but can only set the stage for getting ready for it.  This tangent is hopefully interesting for those of you that want to play with the SDK.  Personally I find the take picture API very interesting with quite a bit of potential.

Back on track now.  One last thing to clarify.  In order to get this same information in case you do not have an internet connection, just use a web browser to open “c:\program files (x86)\citrix\mobilitysdk\doc\html\index.html” assuming that you installed to the default path on an x64 system.  On IE, it will give a popup warning against running scripts.  Let the scripts run since it will create the navigation pane.  There is no ActiveX in the SDK.

It has been a real challenge to produce the SDK documentation this way and there is certainly room for improvement.  This is the first time I have used doxygen for so much.  It is an incredibly powerful tool and hopefully the SDK will use more of its features in the future.

Since we just announced XAMP and XAMA just a few days ago, and it also very close to the holidays, it is not expected that many people will get a chance to try these solutions before January.

However, to anticipate potential questions, there is a solution regardless of when the questions are asked.

First of all, there is a Citrix forum dedicated to the XAMA SDK.  There has not yet been much traffic here yet but we have had a few questions.  The forum is the place to go when you have an issue with getting the SDK to work.   So far we have covered some of the issues that happen when you first start and also how to debug.  Thanks go out to Jason Conger for being an early adopter.   Just remember that we are instantly notified of any new request and do our best to answer the question within a day.

Another path is to use our direct email account.  The group that worked on the Mobility Pack has a group email alias.  This address is mobilitysdk (at) citrix.com.  As usual, substitute “(at)” with @.  I wrote it this way in the vain attempt to hide the email address from automated programs.

The email address is direct and instant and is directed to several people in Citrix.    It probably comes down to preference whether you want to use the forum or email.  Either way, you will get the help you need with the XAMA SDK.

When a developer first experiments with mobile phones and tablets, one of the first questions is how it can be debugged.  With PCs it is fairly easy to start a debugger for a program since the environment is well established and there is plenty of screen space.  With a phone, the space is very limited.  On top of this, there is very limited input control.  Using touch is very effective for mobile devices but not always that effective for debugging the applications than run on these devices.  There has to be some kind of outside control to make this more effective.

There are some general strategies:

1. Using tracing to log files
2. Using tracing to remote consoles
3. Interactive Debugging inside session
4. Interactive Debugging in another session

Each has merits but each one represents a more difficult layer to achieve.

Tracing to Log Files

The pros are that it is really easy to write code to include trace statements.  These trace statements are typically disabled for retail builds.  The tracing usually ends up in a log file with time stamps so that the situation can later be diagnosed.  Typically this would be used with real customer issues that are not under the control of a developer.  The trace statements can be helpful but only if the volume of data is not too large and the trace covers areas that are broken.  It is fairly easy to miss detail with trace statements since it cannot be easily predicted what will be a problem.  If the developer thought it would be a problem, it would already be fixed.

Also, the output file is collected after everything has happened.  There is no chance of gathering more or less data around the time of the event.

Tracing to Debug Console

The concept of outputting to a debug console makes the trace more live.  It might be possible to select levels of debug information.  It might also be possible to pick certain categories of trace information.  This makes the log information more selective and the trace information is shown when the events happen.  However, it is still a trace.  There is no option for examining specific execution of lines of code.  There is also no ability to change any variables or set breakpoints.  It is better than a log file trace but still not always enough.

Interactive Debugging in Same Session

Most Windows developers use an IDE (Integrated Development Environment) to work with and debug programs.  Working with text traces is often not enough to determine what the problem is.  Modern applications are based on advanced techniques that can only be captured using an application focused on debugging.   Most Windows developers can focus on debugging inside Windows using Visual Studio in the same session.  It is not hard to have a debugger running at the same time as the application.  The application alternates being in the foreground with the debugger based on whether it is running or being debugged.

There is a lot of power behind this model.  It allows for a widespread coverage that is much easier to work with than tracing.  It is possible to pause the program at any time either from breakpoints or pressing the break button.  Once stopped, the variables can be examined and potentially changed.  The call stack can be examined.  Memory can be viewed.  The path of execution can be observed step by step.

However, this model would not suitable to mobile phones.  First of all, the devices are much too small to allow something like Visual Studio to run well.  Second, the controls for Visual Studio are too small on high density pixel devices.

It is possible to use a tablet with Visual Studio but the process is too frustrating to use for too long.  Touching such small elements has the potential for error which sometimes leads to unwanted closures.

Interactive Debugging in Another Session

This is the most advanced use case but also the most useful.  Given that we are using a WTS-based server, it is completely valid to use another session.  This strategy is newer than the others and therefore the most unproven.  However, in the workings of supporting mobile devices, sometimes you need to do something  like this.

Here is what I did to get it working:

1. Install Visual Studio 2010 onto the XenApp 6.5 server that has XAMP (XenApp 6.5 Mobility Pack)
2. Have two different accounts (one user, one administrator)
3. Login to the administrator and start Visual Studio
4. Login to the user with a mobile device
5. Start the application for the user (but do not do anything yet)
6. As administrator, on the Visual Studio, select Debug/Attach To Process
7. Click the two checkboxes for showing processes for users and sessions
8. Sort the process names and find your user program and select it
9. Attach to the program (the program should continue to run after this happens)
10. Break into the program and make sure the symbols are set correctly for the program
11. Set any desired breakpoints
12. Use the program as a user

There are weaknesses with this model (complexity) and it does not cover controlling the application from the beginning.  This could be handled by having a stub code section that waits before launching the main part of the program.

However it does work and gives use two main things:

1. The debugger can be used fully like it was meant to be used on Windows
2. The application is not affected by the debugger being displayed in the same session.

It is important that the administrator has rights to debug any program in the system.  I do not remember doing anything special for this so it should just work.

This gives the application and the debug view different display surfaces.  Best of all, the debugger can use the standard keyboard and mouse.

It is possible to do the other three tactics with mobile applications but each of these have serious limitations.  One strong exception to this is time sensitive activities.  Sometimes debugging slows things down enough that it can affect the outcome.  The most obvious reason is network transactions.  If the requests do not get a response within a certain time, the request will fail.

In this realm, using tracing is actually better.  It is just important to make sure there is enough information in the trace and the trace has an accurate time reference.

Debugging, to me, has always been more of an art than a science.  The situation largely determines how it can be attacked.  Developers have different preferences and obviously this is reflected by what tools they use and how much experience they have fixing problems.  Even though it might be a bit painful to use the most advanced option for debugging mobile device applications with XenApp, it is also the most rewarding way to get results.

I did not mention how to get administrator access to the server.  In my case, I used XenServer to access the console of the server.  From this “local” console, I logged on as administrator and started Visual Studio.  I should have also mentioned that XenServer is hosting my copy of XenApp.  As a Citrix developer, using XenServer makes it much easier to try different servers as well as including support servers like AD controller.  Last I heard, XenServer is still available free.

However, it would also be possible to either use ICA or RDP to access the server remotely to run Visual Studio.

The first version of the Citrix XenApp 6.5 Mobile Application (XAMA) SDK has been published on the Citrix web site as of December 17, 2011.  In order to use the SDK, the XenApp server must have the Citrix XenApp 6.5 Mobility Pack (XAMP) installed first.  The team has worked for around a year bringing this together.  The overall goal is to make it easy for enterprise Windows developers write software that works well on mobile devices (phones and tablets).

Currently the Android Receiver supports this new programming platform with the iOS Receiver to follow soon.  The main Android Receiver has the required code to support applications using XAMA.

The basic things that would need to be done:

1.  Setup a test XenApp 6.5 server
2.  Install the XenApp 6.5 Mobility Pack on the XenApp server
3. Install XenApp 6.5 Mobility Application SDK on Windows 7 64-bit dev machine
4. Install Citrix Receiver for Android (minimum 3.0.59 version) on Android device

More tips:

1. Select Web Interface for XenApp to test apps/desktops
2. Use XenServer to host XenApp and other support servers (like AD controller)
3. Learn about Google Android SDK and hook up the phone/tablet with USB debugging
4. Use client drive access or Windows Network to exchange files between server and dev machine (Windows Network is faster)
5. Visual Studio 2010 is best to use with server and dev machine
6. XAMA SDK is has HTML documentation included in SDK.  Just open the index.html in the doc\html directory with web browser.  Or, go online at http://www.citrixcloud.net/mobilesdk/.

The primary concept is that the SDK enables Windows applications to be aware of mobile device features.  Once aware, these applications can utilize the features to accomplish things which were not possible before.  Currently the most obvious benefit is being able to customize content to the variable screen sizes and pixel densities.  Long-term, full integration will allow for powerful bonding between server applications and mobile devices.  The best of both worlds will bring a better experience to the users.

 

Ramping up with XAMP

Over the last couple of years, Citrix Labs has been working on a project to make standard Windows applications more usable on mobile devices (phones and tablets).  This started with the development of Project GoldenGate and the production of an email client that runs on XenApp but acts like a native mobile device application when run remotely.  In the early demonstrations, it was clear that customers were interested for a few different reasons:

• The email would be kept in the data center and therefore would be more secure.  If the device was lost or stolen, the information would not be there.
• The email application could be maintained inside the organization instead of on different devices at remote locations.
• Deploying standard Windows email programs via XenApp is not easy due to user expectations for usability.

You can learn more about the latest release of GoldenGate here.

Producing this kind of application is important but not the whole story.  There is also a need to make it easy for other software companies to produce software for XenApp and mobile devices.  The intent is to publish a SDK for developers to use to get all the same benefits along with a few new ideas along the way.

To get a first impression of this SDK, please example the doxygen-generated documenation for XenApp 6.5 Mobile Application SDK.  This documentation was released during Synergy Barcelona in late October 2011.

The online documentation focuses on the C/C++ interfaces for the SDK.  The internal name for the SDK was Citrix Mobility Pack SDK (CMPSDK).  That is why there are so many references to CMP in the documentation.

The announcement for the XA MA SDK includes a video that share the vision for producing these kind of mobile applications.

It is important to keep these kind of things in mind:

• It is a fairly steep learning curve to pick up knowledge in mobile device platform development.  It is far easier to leverage existing Windows development experience.
• The XA Mobility Pack enables several new features from the mobile device including GPS, display metrics, onscreen keyboard, SMS, camera, orientation, mobile device properties,  button redirection, user notification, picker control support.
• The SDK works with C/C++/COM/C#
• The SDK is used by GoldenGate

There is another way to talk about this SDK.  What it really means is that the client and server work closer together to produce a more native experience on the mobile device.  It also means that the mobile device gets all the benefits of the data center with the massive storage and the existing Windows infrastructure.  As an example, a Windows program could be written to use the SDK to take a picture on the device and then download the picture to any location inside the company.  There is more to the story than this.  Security is a concern.  So, for example, no automatic picture taking will happen and the server will need access to the mobile device storage through Client Drive Mapping.  However, the point is that with a bit of changes, an existing Windows program could be modified to take advantage of the features on the mobile device.  Another example is a dialing program.  Using our SDK, it is possible to tell the device to start the process of dialing the number.  The user still has to say that it is okay and let the dial happen (for security reasons).  This would make it possible to write a program that could hook into the company database and then provide a list of names based on a search.  Once a person is selected, that number will be sent to the phone so the user can dial it easily without typos or the possibility of errors with the prefix.

Yet another angle brings in GPS data.  The SDK introduces the ability to determine current location.  With this information it would be possible to reconfigure the software to provide different results.  For example, the dialer would know where it is so it can pick the right prefix to dial the number correctly.

For those early developers for this SDK, there is a forum setup in Citrix.  The forum is monitored by the people that have been working on it and the associated projects.  The team is keen to help developers and to learn what else developers would like to see.

Just to give you a simple example of code, here is a example of how to dial a number:

//
// Phonecall example:
//
// Uses Citrix Mobility SDK to start a phone call
//
// Copyright (c) Citrix Systems
//

#include <stdio.h>
#include <windows.h>

#include <cmp.h>

// change the phone number to something more appropriate
#define PHONE_NUMBER “+18005551212″

// unique number should not be a constant but it is here for an example
#define UNIQUE_CALL_ID 0×87654321

//
// Event callback for phone call started
//
void CMPAPI PhoneCallStarted(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID PhoneCallId)
{
printf(“PhoneCallStarted hCMP(%p) rc(0x%X) PhoneCallId(%X)\n”, hCMP, rc, PhoneCallId);
}

//
// Reports errors if they happen
//
void ReportStatus(LPCSTR text, CMPRESULT rc)
{
// only print if something went wrong
if(CMP_FAILURE(rc))
{
printf(“%s CMPResult(%08X)\n”, text, rc);
}

return;
}

//
// main entry point for simple phone call program
//
int __cdecl main(int argc, char **argv)
{
CMPRESULT rc;
HANDLE hCMP = NULL;

// initialize for STA (Single Thread Apartment) in COM
rc = CMPInitialize(FALSE);

ReportStatus(“CMPInitialize”, rc);

// Open a handle to the mobile device
rc = CMPOpen(&hCMP);

ReportStatus(“CMPOpen”, rc);

if(CMP_SUCCESS(rc))
{
// open the link between the two sides
rc = CMPOpenSession(hCMP);

ReportStatus(“CMPOpenSession”, rc);

if(CMP_SUCCESS(rc))
{
// register for event
rc = CMPRegisterForEvent(hCMP, CMP_EVENT_PHONE_CALL_STARTED, (CMP_EVENT_CALLBACK)PhoneCallStarted);

ReportStatus(“CMPRegisterForEvent CMP_EVENT_PHONE_CALL_STARTED”, rc);

// Start the phone call process by popping up the dialer with the number already populated
rc = CMPStartCall(hCMP, PHONE_NUMBER, UNIQUE_CALL_ID);

ReportStatus(“CMPStartCall”, rc);

// let events come in over the next 30 seconds
//
// if this was a Windows program and we had a message loop, we would not need to do this
for(int i=0; i<30; i++)
{
Sleep(1000);
}

// close our connection
CMPCloseSession(hCMP);
}

// release our handle
CMPClose(hCMP);
}

// uninitialize COM
CMPUninitialize();

}

This shows the typical flow for how to use the SDK.

1. CMPInitialize
2. CMPOpen
3. CMPOpenSession
4. CMP functions (e.g. CMPStartCall)
5. CMPCloseSession
6. CMPClose
7. CMPUninitialize

The calls are matched up.  CMPInitialize and CMPUninitialize, CMPOpen and CMPClose, and CMPOpenSession and CMPCloseSession.

CMPInitialize corresponds to initializing a thread for COM.  It should only be done once for a thread and before any COM operations happen.  The SDK uses COM so it needs this to be run.  If COM is already initialized then you can skip this function.

CMPOpen creates the COM object for the SDK.  It is responsible for creating and initializing the COM interface.  CMPOpen does not guarantee a connection to the mobile device.  It will return fine even if the connection is not there.

CMPOpenSession establishes a link between the two sides (server and mobile device).  It will fail if the device is not there.  For any of the functions besides the paired ones already mentioned, require a connection to the mobile device.  If you try to issue a function when it is not connected, it will fail.

The functions in the SDK use a return code called CMPRESULT.  This enumeration is defined in cmpenum.h in the SDK and has this pattern.  If the lower 16-bits (word) are zero, then the command was successful.  The top 16-bits reveal which component generated the result.  The status codes are custom to the SDK to avoid depending on the Windows error codes too much.

To download the SDK that was released with Synergy, get it from CDN.