Note: This blog post first appeared at http://citrixblogger.org and is being reposted here for a broader Citrix audience.
During the initial development of XenApp Mobile Pack, certain choices were made for the status/error codes. This all made sense during that time but certain topics have come up since then which requires attention. Nothing serious, but rather more of an indication that things need to be better explained.
Chain of thought:
- Most of the XAMA API return CMPRESULT
- CMPRESULT is a 32-bit signed number
- CMPRESULT is directly related to CMP_ERROR_ID
- CMP_ERROR_ID is an enumeration in the cmpenum.h include file in the SDK
- Each CMP_RESULT_ID entry uses the STATUS_CODE macro to build the status code (error code)
- The macro takes two parameters: the component id, and the error number
- The two numbers are 16-bit each and combine to form the 32-bit status code (the component id is the high word and the error number is the low word).
- When the error number(low word) is zero, it is considered a successful operation. Having a non-zero status code could mean that it was successful. It is necessary to mask the high word to determine success.
The pattern is similar to how Microsoft has documented its Windows API return codes. The major difference is that the codes between Windows and XAMA API do not correspond. Said another way, the status codes for XAMA cannot be used against Windows status codes.
Even though there was some overlap between Windows and XAMA, there were several areas that only XAMA had status codes. It was necessary to use our own status codes. This is a good strategy in order to support as many different receivers as possible. Since our status codes have a well known limit of codes, all our server and Receiver code can act separate from the platform they run on. The MRVC channel exchanges these status codes and it would not have made to leave it open to unlimited error code pattern. That is probably a bit too much detail.
One of the goals of this post is to include a document for the current XAMA API StatusCodes
This PDF includes all the current status codes with the hexadecimal values and a brief description. Based on a few different events inside and outside Citrix, it has become clear that mapping the hex code to an error message is very valuable. Until it is more automated, this chart should help to find a match.
The most common errors report to me are 0x120008 and 0x002C. These translate into CMP_ERROR_GVCH_NOT_CONNECTED_STATE (0x120008) and CMP_ERROR_CLIENT_DRIVE_UNAVAILABLE (0x002C).
GVCH stands for Generic Virtual Channel. This error just means that there is no connection to the mobile device using MRVC (Mobile Receiver Virtual Channel). There are a number of likely causes:
- The Mobile Receiver version does not support XAMP/XAMA with MRVC.
- The session is currently disconnected
- The Mobile Receiver might have MRVC support turned off. (currently not a problem but could be in the future)
As for CMP_ERROR_CLIENT_DRIVE_UNAVAILABLE, the most common reason is that Android Receiver has Client Drive Mapping (CDM) turned off. It is necessary to edit the settings on the Android Receiver to all read or full access to the SD card. This error should only appear if there is an attempt to take a picture with the API and CDM is not enabled on both sides. Since it is the default to turn CDM off on Android Receiver, that is why this error has happened so often.
We are in the process of updating the documentation to better explain the status codes and include the hex values. This upgrade to online documentation should come in the following weeks if not sooner.