Mobile SDK for Windows Apps2.0
Transforming Windows apps into Mobile apps
cmp.h File Reference

CMPAPI - Public C Interfaces for Citrix Mobility Pack. More...

#include <cmptypes.h>
#include <cmpcap.h>
#include <cmpenum.h>
#include <cmpflags.h>
#include <cmpstruct.h>
#include <OleAuto.h>
#include <cmpresult.h>

Go to the source code of this file.

Classes

struct  CMP_FILEVERSION
 File version data. More...
struct  CMP_VERSION
 Version information about CMPAPI. More...

Defines

#define CMPCALL   __stdcall
#define CMPAPI   CMPCALL
#define CMPEXPORT   __declspec(dllexport)
#define CMPIMPORT   __declspec(dllimport)
#define CMPCDECL   __cdecl
#define CMPAPIENTRY   CMPEXPORT CMPRESULT CMPCALL
#define CMP_CDECL_APIENTRY   CMPEXPORT CMPRESULT CMPCDECL
#define CMP_VERSION_MAJOR   2
#define CMP_VERSION_MINOR   0
#define CMP_VERSION_ONE_MAJOR   1
#define CMP_VERSION_ONE_MINOR   0
#define CMP_VERSION_TWO_MAJOR   2
#define CMP_VERSION_TWO_MINOR   0

Typedefs

typedef char * UTF8_STRING
typedef PVOID CMP_EVENT_CALLBACK
typedef struct CMP_FILEVERSION CMP_FILEVERSION
typedef struct CMP_VERSION CMP_VERSION
typedef CMP_BUTTON_ID buttonId
typedef INT16 MetricFlags
typedef INT16 INT32 pixelWidth
typedef INT16 INT32 INT32 pixelHeight
typedef INT16 INT32 INT32 INT16 colorDepth
typedef INT16 INT32 INT32
INT16 INT32 
XPixelsPerInch
typedef INT16 INT32 INT32
INT16 INT32 INT32 
YPixelsPerInch
typedef INT16 INT32 INT32
INT16 INT32 INT32
CMP_ORIENTATION_POSITION 
orientation
typedef INT16 INT32 INT32
INT16 INT32 INT32
CMP_ORIENTATION_POSITION INT32 
WidthMilliInches
typedef INT16 INT32 INT32
INT16 INT32 INT32
CMP_ORIENTATION_POSITION INT32
INT32 
HeightMilliInches
typedef INT16 INT32 INT32
INT16 INT32 INT32
CMP_ORIENTATION_POSITION INT32
INT32 INT32 
NormalizedDPI
typedef void(CMPCALLPFN_EVENT_ORIENTATION_CHANGED )(HANDLE hCMP, CMPRESULT rc, CMP_ORIENTATION_POSITION deviceOrientation, CMP_ORIENTATION_POSITION appOrientation, UINT16 orientationFlags)
typedef void(CMPCALLPFN_EVENT_SCROLL_MODE_CHANGED )(HANDLE hCMP, CMPRESULT rc, CMP_SCROLL_MODE scrollMode)
typedef void(CMPCALLPFN_EVENT_KEYBOARD_STATE_CHANGED )(HANDLE hCMP, CMPRESULT rc, CMP_KEYBOARD_TYPE keyboardType, INT16 keyboardStateFlags, CMP_KEYBOARD_AUTOCAPS kybdAutoCap, CMP_KEYBOARD_RETURNKEY kybdReturnKey)
typedef void(CMPCALLPFN_EVENT_VIEWPORT_ORIGIN_CHANGED )(HANDLE hCMP, CMPRESULT rc, INT32 left, INT32 top)
typedef void(CMPCALLPFN_EVENT_VIEWPORT_CHANGED )(HANDLE hCMP, CMPRESULT rc, INT16 flags, INT16 zoomFactor, INT32 x0Server, INT32 y0Server, INT32 x1Server, INT32 y1Server, INT32 x0Client, INT32 y0Client, INT32 x1Client, INT32 y1Client)
typedef void(CMPCALLPFN_EVENT_BUTTON_TARGET_CHANGED )(HANDLE hCMP, CMPRESULT rc, CMP_BUTTON_ID buttonId, CMP_BUTTON_TARGET buttonTarget)
typedef void(CMPCALLPFN_EVENT_CONTROL_STATE_CHANGED )(HANDLE hCMP, CMPRESULT rc, UINT16 controlStateFlags)
typedef void(CMPCALLPFN_EVENT_SMS_STARTED )(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID SMSId)
typedef void(CMPCALLPFN_EVENT_PHONE_CALL_STARTED )(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID phoneCallId)
typedef void(CMPCALLPFN_EVENT_PICKER_CONTROL_STATE_CHANGED )(HANDLE hCMP, CMP_UNIQUE_ID pickerId, INT16 pickerStateFlags, CMPRESULT rc, INT16 selectedIndex)
typedef void(CMPCALLPFN_EVENT_CAMERA_PICTURE_TAKEN )(HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_ID pictureId, CMP_IMAGE_FORMAT pictureFormat, UINT32 pictureSize, UTF8_STRING filename)
typedef void(CMPCALLPFN_EVENT_FILTER_CHANGED )(HANDLE hCMP, CMPRESULT rc, CMP_EVENT_ID eventId, INT16 filterFlags)
typedef void(CMPCALLPFN_EVENT_USER_NOTIFIED )(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID notificationId)
typedef void(CMPCALLPFN_EVENT_CAMERA_PICTURE_REMOVED )(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID pictureId)
typedef void(CMPCALLPFN_EVENT_SESSION_STATE_CHANGED )(HANDLE hCMP, CMP_SESSION_STATE state)
typedef void(CMPCALLPFN_EVENT_CHANNEL_STATE_CHANGED )(HANDLE hCMP, CMP_CHANNEL_STATE state)
typedef void(CMPCALLPFN_EVENT_PICTURE_CAPTURED )(HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID uniqueId, UTF8_STRING pictureMetadata, UTF8_STRING filename, UTF8_STRING thumbnail, UINT32 pictureSize, const CMP_CAPTURE_PICTURE_OPTIONS *options)
typedef void(CMPCALLPFN_EVENT_VIDEO_CAPTURED )(HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID uniqueId, UTF8_STRING videoMetadata, UTF8_STRING filename, UINT32 videoSize, const CMP_CAPTURE_VIDEO_OPTIONS *options)
typedef void(CMPCALLPFN_EVENT_AUDIO_CAPTURED )(HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID uniqueId, UTF8_STRING audioMetadata, UTF8_STRING filename, UINT32 audioSize, const CMP_CAPTURE_AUDIO_OPTIONS *options)
typedef void(CMPCALLPFN_EVENT_SUPPORTED_ORIENTATIONS_CHANGED )(HANDLE hCMP, CMPRESULT result, CMP_SUPPORTED_ORIENTATIONS supportedOrientation)
typedef void(CMPCALLPFN_EVENT_APP_FOREGROUND )(HANDLE hCMP)
typedef void(CMPCALLPFN_EVENT_APP_BACKGROUND )(HANDLE hCMP)
typedef void(CMPCALLPFN_EVENT_FOREGROUND_APP_CHANGED )(HANDLE hCMP, DWORD foregroundProcessId)
typedef void(CMPCALLPFN_EVENT_CAPTURE_MEDIA_REMOVED )(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_LONG_ID captureId)

Functions

CMPAPIENTRY CMPInitialize (BOOL MultiThreaded)
 Initialize COM for CMP.
CMPAPIENTRY CMPUninitialize ()
 Uninitialize COM for CMP.
CMPAPIENTRY CMPOpen (HANDLE *phCMP)
 Create Citrix mobile device object and return a handle.
CMPAPIENTRY CMPClose (HANDLE hCMP)
 Close Citrix mobile device object handle.
CMPAPIENTRY CMPGetAPIVersion (HANDLE hCMP, CMP_VERSION *cmpVersion)
 Get CMP API Version.
CMPAPIENTRY CMPGetDLLPath (HANDLE hCMP, LPCSTR DLLfilename, LPSTR DLLfilepath, UINT32 pathLength)
 Get DLL Path for a given CMP-related DLL name.
CMPAPIENTRY CMPProcessDetect (HANDLE hCMP, DWORD processId, PBOOL detectFlag)
 Detect if a process is using the Citrix Mobility Pack.
CMPAPIENTRY CMPRegisterProcess (HANDLE hCMP, DWORD processId)
 Register a process for Citrix Mobility Pack.
CMPAPIENTRY CMPUnregisterProcess (HANDLE hCMP, DWORD processId)
 Unregister a process for CMP.
CMPAPIENTRY CMPOpenSession (HANDLE hCMP)
 Open session connection.
CMPAPIENTRY CMPCloseSession (HANDLE hCMP)
 Close session connection.
CMPAPIENTRY CMPSetSessionOptionBool (HANDLE hCMP, CMP_SESSION_OPTION option, BOOL value)
 Set boolean session option.
CMPAPIENTRY CMPGetSessionOptionBool (HANDLE hCMP, CMP_SESSION_OPTION option, BOOL *value)
 Get boolean session option.
CMPAPIENTRY CMPGetSessionState (HANDLE hCMP, CMP_SESSION_STATE *sessionState)
 Get the current session state.
CMPAPIENTRY CMPGetButtonTarget (HANDLE hCMP, CMP_BUTTON_ID buttonId, CMP_BUTTON_TARGET *buttonTarget)
 Get button target.
CMPAPIENTRY CMPSetButtonTarget (HANDLE hCMP, CMP_BUTTON_ID buttonId, CMP_BUTTON_TARGET buttonTarget)
 Set button target.
CMPAPIENTRY CMPTakePicture (HANDLE hCMP, CMP_UNIQUE_ID pictureId, CMP_IMAGE_FORMAT imageFormat)
 Start the process of taking a picture.
CMPAPIENTRY CMPGetPictureFilename (HANDLE hCMP, CMP_UNIQUE_ID pictureId, UTF8_STRING filename, UINT32 bufferLength, PUINT32 returnedLength)
 Get the name of the picture file.
CMPAPIENTRY CMPGetPictureState (HANDLE hCMP, CMP_UNIQUE_ID pictureId, PUINT32 size, CMP_PICTURE_STATE *pictState)
 Get picture state.
CMPAPIENTRY CMPRemovePicture (HANDLE hCMP, CMP_UNIQUE_ID pictureId)
 Remove picture.
CMPAPIENTRY CMPGetControlsFlags (HANDLE hCMP, PUINT16 controlFlags)
 Get Receiver controls flags.
CMPAPIENTRY CMPDisableControls (HANDLE hCMP)
 Disable Receiver controls.
CMPAPIENTRY CMPEnableControls (HANDLE hCMP)
 Enable the Receiver Controls for use. Only the Apple iOS Receiver has a visible receiver control. This function makes the controls visible.
CMPAPIENTRY CMPGetDevicePropertyBool (HANDLE hCMP, CMP_DEV_BOOL_PROP_ID propertyId, BOOL *value)
 Get device boolean property.
CMPAPIENTRY CMPGetDevicePropertyString (HANDLE hCMP, CMP_DEV_STRING_PROP_ID propertyId, UTF8_STRING propertyString, UINT32 propertyBufferSize, PUINT32 returnedSize)
 Get device property string.
CMPAPIENTRY CMPGetOrientation (HANDLE hCMP, CMP_ORIENTATION_DATA *orientationData)
 Get orientation.
CMPAPIENTRY CMPSetOrientation (HANDLE hCMP, CMP_ORIENTATION_POSITION orientation, UINT16 orientationFlags)
 Set orientation.
CMPAPIENTRY CMPGetScrollMode (HANDLE hCMP, CMP_SCROLL_MODE *scrollMode)
 Get scroll mode.
CMPAPIENTRY CMPSetScrollMode (HANDLE hCMP, CMP_SCROLL_MODE scrollMode)
 Set scroll mode.
CMPAPIENTRY CMPGetDisplaySettings (HANDLE hCMP, CMP_DISPLAY_SETTINGS *dispSettings)
 Get display settings.
CMPAPIENTRY CMPGetViewportOrigin (HANDLE hCMP, CMP_DISPLAY_POINT *pt)
 Get viewport origin.
CMPAPIENTRY CMPSetViewportOrigin (HANDLE hCMP, CMP_DISPLAY_POINT *pt, UINT16 viewportFlags)
 Set viewport origin.
CMPAPIENTRY CMPGetViewport (HANDLE hCMP, INT16 *flags, INT16 *zoomFactor, CMP_DISPLAY_RECT *serverViewport, CMP_DISPLAY_RECT *clientViewport)
 Get viewport.
CMPAPIENTRY CMPSetViewport (HANDLE hCMP, INT16 flags, INT16 zoomFactor, CMP_DISPLAY_RECT *serverViewport)
 Set viewport.
CMPAPIENTRY CMPGetKeyboardState (HANDLE hCMP, CMP_KEYBOARD_STATE *kybdState)
 Get keyboard state.
CMPAPIENTRY CMPShowKeyboard (HANDLE hCMP, CMP_KEYBOARD_STATE *kybdState)
 Show the display keyboard.
CMPAPIENTRY CMPHideKeyboard (HANDLE hCMP)
 Hide display keyboard.
CMPAPIENTRY CMPSendSMS (HANDLE hCMP, UTF8_STRING phoneNumber, CMP_UNIQUE_ID msgId, UTF8_STRING SMSText)
 Send SMS.
CMPAPIENTRY CMPStartCall (HANDLE hCMP, UTF8_STRING phoneNumber, CMP_UNIQUE_ID callId)
 Start phone call.
CMPAPIENTRY CMPShowPicker (HANDLE hCMP, CMP_UNIQUE_ID controlId, CMP_DISPLAY_RECT *rect, UINT32 selectedIndex, UINT32 listItemsCount, UTF8_STRING listItems, UTF8_STRING title)
 Show picker control.
CMPAPIENTRY CMPShowPickerUTF16 (HANDLE hCMP, CMP_UNIQUE_ID controlId, CMP_DISPLAY_RECT *rect, UINT32 selectedIndex, UINT32 listItemsCount, LPCWSTR listItems, LPCWSTR title)
 Show picker control using wide characters.
CMPAPIENTRY CMPHidePicker (HANDLE hCMP, CMP_UNIQUE_ID controlId)
 Hide picker control.
CMPAPIENTRY CMPGetPickerState (HANDLE hCMP, CMP_UNIQUE_ID controlId, PUINT16 pickerState)
 Get current picker control state.
CMPAPIENTRY CMPGetCapabilityBool (HANDLE hCMP, CMP_CAP_ID capID, UINT16 keyId, PBOOL value)
 Get capability boolean value.
CMPAPIENTRY CMPGetCapabilityInt16 (HANDLE hCMP, CMP_CAP_ID CapID, UINT16 KeyId, PINT16 Value)
 Get capability INT16 value.
CMPAPIENTRY CMPGetCapabilityUInt16 (HANDLE hCMP, CMP_CAP_ID capID, UINT16 keyId, PUINT16 value)
 Get capability UINT16 value.
CMPAPIENTRY CMPGetCapabilityInt32 (HANDLE hCMP, CMP_CAP_ID capID, UINT16 keyId, PINT32 value)
 Get capability INT32 value.
CMPAPIENTRY CMPGetCapabilityUInt32 (HANDLE hCMP, CMP_CAP_ID capID, UINT16 keyId, PUINT32 value)
 Get capability UINT32 value.
CMPAPIENTRY CMPNotifyUser (HANDLE hCMP, CMP_UNIQUE_ID notificationId, USHORT notificationFlags, UTF8_STRING notificationText)
 Notify user of event.
CMPAPIENTRY CMPGetChannelState (HANDLE hCMP, CMP_CHANNEL_STATE *state)
 Get the current channel state.
CMPAPIENTRY CMPFilterEvent (HANDLE hCMP, CMP_EVENT_ID eventId, UINT16 filterFlags)
 Filter specific events.
CMPAPIENTRY CMPOpenForProcess (HANDLE *phCMP, DWORD processId)
 Create Citrix mobile device object for a specific process and return a handle.
CMPAPIENTRY CMPCapturePicture (HANDLE hCMP, const CMP_CAPTURE_PICTURE_OPTIONS *options, CMP_UNIQUE_LONG_ID *pictureId)
 Capture a picture.
CMPAPIENTRY CMPCaptureVideo (HANDLE hCMP, const CMP_CAPTURE_VIDEO_OPTIONS *options, CMP_UNIQUE_LONG_ID *videoId)
 Capture a video clip.
CMPAPIENTRY CMPCaptureAudio (HANDLE hCMP, const CMP_CAPTURE_AUDIO_OPTIONS *options, CMP_UNIQUE_LONG_ID *audioId)
 Capture a audio clip.
CMPAPIENTRY CMPRemoveCapturedData (HANDLE hCMP, CMP_UNIQUE_LONG_ID captureId)
 Remove the files associated with the original capture.
CMPAPIENTRY CMPSetSupportedOrientations (HANDLE hCMP, CMP_SUPPORTED_ORIENTATIONS supportedOrientations)
 Set which orientations the application is going to support.
CMPAPIENTRY CMPGetSupportedOrientations (HANDLE hCMP, CMP_SUPPORTED_ORIENTATIONS *supportedOrientations)
 Get which orientations the application is going to support.
CMPAPIENTRY CMPRegisterForEvent (HANDLE hCMP, CMP_EVENT_ID eventId, CMP_EVENT_CALLBACK eventHandler)
 Register event handler.
CMPAPIENTRY CMPUnregisterForEvent (HANDLE hCMP, CMP_EVENT_ID eventId, CMP_EVENT_CALLBACK eventHandler)
 Unregister event handler.
typedef void (CMPCALL *PFN_EVENT_BUTTON_PRESSED)(HANDLE hCMP
void CMPCALL ButtonPressed (HANDLE hCMP, CMP_BUTTON_ID buttonId)
 Event: Device button was pressed.
void CMPCALL DisplaySettingsChanged (HANDLE hCMP, INT16 MetricFlags, INT32 pixelWidth, INT32 pixelHeight, INT16 colorDepth, INT32 XPixelsPerInch, INT32 YPixelsPerInch, CMP_ORIENTATION_POSITION orientation, INT32 WidthMilliInches, INT32 HeightMilliInches, INT32 normalizedDPI)
 Event: Display settings have changed.
void CMPCALL OrientationChanged (HANDLE hCMP, CMPRESULT rc, CMP_ORIENTATION_POSITION deviceOrientation, CMP_ORIENTATION_POSITION appOrientation, UINT16 orientationFlags)
 Event: Orientation changed.
void CMPCALL ScrollModeChanged (HANDLE hCMP, CMPRESULT rc, CMP_SCROLL_MODE scrollMode)
 Event: Scroll mode changed.
void CMPCALL KeyboardStateChanged (HANDLE hCMP, CMPRESULT rc, CMP_KEYBOARD_TYPE keyboardType, INT16 keyboardStateFlags, CMP_KEYBOARD_AUTOCAPS kybdAutoCap, CMP_KEYBOARD_RETURNKEY kybdReturnKey)
 Event: Keyboard state changed.
void CMPCALL ViewportOriginChanged (HANDLE hCMP, CMPRESULT rc, INT32 left, INT32 top)
 Event: Viewport origin changed.
void CMPCALL ButtonTargetChanged (HANDLE hCMP, CMPRESULT rc, CMP_BUTTON_ID buttonId, CMP_BUTTON_TARGET buttonTarget)
 Event: Button target changed.
void CMPCALL ControlStateChanged (HANDLE hCMP, CMPRESULT rc, UINT16 controlStateFlags)
 Event: Control state changed.
void CMPCALL SMSStarted (HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID SMSId)
 Event: Send SMS Started.
void CMPCALL PhoneCallStarted (HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID phoneCallId)
 Event: Phone call started.
void CMPCALL PickerControlStateChanged (HANDLE hCMP, CMP_UNIQUE_ID pickerId, INT16 pickerStateFlags, CMPRESULT rc, INT16 selectedIndex)
 Event: Picker control state changed.
void CMPCALL PictureTaken (HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID pictureId, CMP_IMAGE_FORMAT pictureFormat, UINT32 pictureSize, UTF8_STRING filename)
 Event: Picture taken.
void CMPCALL FilterChanged (HANDLE hCMP, CMPRESULT rc, CMP_EVENT_ID eventId, INT16 filterFlags)
 Event: Filter changed.
void CMPCALL UserNotified (HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID notificationId)
 Event: User notified.
void CMPCALL PictureRemoved (HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID pictureId)
 Event: Picture removed.
void CMPCALL SessionStateChanged (HANDLE hCMP, CMP_SESSION_STATE state)
 Event: Session state changed.
void CMPCALL ChannelStateChanged (HANDLE hCMP, CMP_CHANNEL_STATE state)
 Event: Channel state changed.
void CMPCALL ViewportChanged (HANDLE hCMP, CMPRESULT rc, INT16 flags, INT16 zoomFactor, INT32 x0Server, INT32 y0Server, INT32 x1Server, INT32 y1Server, INT32 x0Client, INT32 y0Client, INT32 x1Client, INT32 y1Client)
 Event: Viewport changed.
void CMPCALL PictureCaptured (HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID uniqueId, UTF8_STRING pictureMetadata, UTF8_STRING filename, UTF8_STRING thumbnail, INT32 pictureSize, const CMP_CAPTURE_PICTURE_OPTIONS *options)
 Event: Picture captured.
void CMPCALL VideoCaptured (HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID uniqueId, UTF8_STRING videoMetadata, UTF8_STRING filename, INT32 videoSize, const CMP_CAPTURE_VIDEO_OPTIONS *options)
 Event: Video captured.
void CMPCALL AudioCaptured (HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID uniqueId, UTF8_STRING audioMetadata, UTF8_STRING filename, INT32 audioSize, const CMP_CAPTURE_AUDIO_OPTIONS *options)
 Event: Audio captured.
void CMPCALL SupportedOrientationsChanged (HANDLE hCMP, CMPRESULT result, CMP_SUPPORTED_ORIENTATIONS supportedOrientations)
 Event: Supported orientations has changed.
void CMPCALL CaptureMediaRemoved (HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID captureId)
 Event: capture media file has been removed from the mobile device.
void CMPCALL AppForeground (HANDLE hCMP)
 Event: Application has foreground.
void CMPCALL AppBackground (HANDLE hCMP)
 Event: Application has background.
void CMPCALL ForegroundAppChanged (HANDLE hCMP, DWORD foregroundProcessId)
 Event: The foreground application has changed to another process.
CMPAPIENTRY UTF16ToUTF8 (LPCWSTR wStr, INT32 wStrLen, UTF8_STRING string, UINT32 bufferSize, UINT32 *stringSize)
 Convert from UTF-16 text to UTF-8.
CMPAPIENTRY UTF8ToBSTR (UTF8_STRING string, INT32 length, BSTR *bStr)
 Convert from UTF-8 text to BSTR.
CMPAPIENTRY GetUTF8MultiStringLength (UTF8_STRING str, UINT32 *length)
 Get length of a UTF-8 multistring in characters.
CMPAPIENTRY GetUTF16MultiStringLength (LPCWSTR str, UINT32 *length)
 Get length of a UTF-16 multistring in characters.
CMPAPIENTRY GetUTF16ToUTF8MultiStringLength (LPCWSTR str, UINT32 *length)
 Get length of a UTF-16 multistring in UTF-8 format.
CMPAPIENTRY UTF8MultiStringToBSTR (UTF8_STRING utf8MultiString, BSTR *bStr)
 Convert a UTF-8 multistring into a single BSTR.
CMPAPIENTRY UTF16ToUTF8MultiString (LPCWSTR wStr, UTF8_STRING multiString, UINT32 stringBufferSize, UINT32 *stringSize)
 Convert a UTF-16 multistring into a UTF-8 multistring.
CMPAPIENTRY BSTRSafearrayToBSTR (SAFEARRAY *psa, BSTR *bstr)
 Convert a BSTR Safearray to a single BSTR for use with multiple string support.
CMPAPIENTRY UTF8ToUTF16Length (UTF8_STRING utf8String, UINT32 *length)
 Calculate the length of a UTF-8 string as if it is really UTF-16.
CMPAPIENTRY UTF16ToUTF8Length (LPCWSTR wString, UINT32 *length)
 Calculate the length of a UTF-16 string as if it is really UTF-8.
CMPAPIENTRY GetUniqueId (CMP_UNIQUE_ID *uniqueId)
 Get a unique Id for the upcoming request that needs one.
CMPAPIENTRY GetUniqueLongId (CMP_UNIQUE_LONG_ID *uniqueId)
 Get a long unique Id for the upcoming request that needs one.

Detailed Description

CMPAPI - Public C Interfaces for Citrix Mobility Pack.


Define Documentation

#define CMP_VERSION_MAJOR   2
#define CMP_VERSION_MINOR   0
#define CMP_VERSION_ONE_MAJOR   1
#define CMP_VERSION_ONE_MINOR   0
#define CMP_VERSION_TWO_MAJOR   2
#define CMP_VERSION_TWO_MINOR   0
#define CMPCDECL   __cdecl
#define CMPEXPORT   __declspec(dllexport)
#define CMPIMPORT   __declspec(dllimport)

Typedef Documentation

typedef PVOID CMP_EVENT_CALLBACK
typedef struct CMP_VERSION CMP_VERSION
typedef INT16 INT32 INT32 INT16 colorDepth
typedef INT16 INT32 INT32 INT16 INT32 INT32 CMP_ORIENTATION_POSITION INT32 INT32 HeightMilliInches
typedef INT16 MetricFlags
typedef INT16 INT32 INT32 INT16 INT32 INT32 CMP_ORIENTATION_POSITION INT32 INT32 INT32 NormalizedDPI
typedef void(CMPCALL * PFN_EVENT_APP_BACKGROUND)(HANDLE hCMP)
typedef void(CMPCALL * PFN_EVENT_APP_FOREGROUND)(HANDLE hCMP)
typedef void(CMPCALL * PFN_EVENT_AUDIO_CAPTURED)(HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID uniqueId, UTF8_STRING audioMetadata, UTF8_STRING filename, UINT32 audioSize, const CMP_CAPTURE_AUDIO_OPTIONS *options)
typedef void(CMPCALL * PFN_EVENT_CAMERA_PICTURE_REMOVED)(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID pictureId)
typedef void(CMPCALL * PFN_EVENT_CAMERA_PICTURE_TAKEN)(HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_ID pictureId, CMP_IMAGE_FORMAT pictureFormat, UINT32 pictureSize, UTF8_STRING filename)
typedef void(CMPCALL * PFN_EVENT_CONTROL_STATE_CHANGED)(HANDLE hCMP, CMPRESULT rc, UINT16 controlStateFlags)
typedef void(CMPCALL * PFN_EVENT_FILTER_CHANGED)(HANDLE hCMP, CMPRESULT rc, CMP_EVENT_ID eventId, INT16 filterFlags)
typedef void(CMPCALL * PFN_EVENT_FOREGROUND_APP_CHANGED)(HANDLE hCMP, DWORD foregroundProcessId)
typedef void(CMPCALL * PFN_EVENT_KEYBOARD_STATE_CHANGED)(HANDLE hCMP, CMPRESULT rc, CMP_KEYBOARD_TYPE keyboardType, INT16 keyboardStateFlags, CMP_KEYBOARD_AUTOCAPS kybdAutoCap, CMP_KEYBOARD_RETURNKEY kybdReturnKey)
typedef void(CMPCALL * PFN_EVENT_ORIENTATION_CHANGED)(HANDLE hCMP, CMPRESULT rc, CMP_ORIENTATION_POSITION deviceOrientation, CMP_ORIENTATION_POSITION appOrientation, UINT16 orientationFlags)
typedef void(CMPCALL * PFN_EVENT_PHONE_CALL_STARTED)(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID phoneCallId)
typedef void(CMPCALL * PFN_EVENT_PICKER_CONTROL_STATE_CHANGED)(HANDLE hCMP, CMP_UNIQUE_ID pickerId, INT16 pickerStateFlags, CMPRESULT rc, INT16 selectedIndex)
typedef void(CMPCALL * PFN_EVENT_PICTURE_CAPTURED)(HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID uniqueId, UTF8_STRING pictureMetadata, UTF8_STRING filename, UTF8_STRING thumbnail, UINT32 pictureSize, const CMP_CAPTURE_PICTURE_OPTIONS *options)
typedef void(CMPCALL * PFN_EVENT_SCROLL_MODE_CHANGED)(HANDLE hCMP, CMPRESULT rc, CMP_SCROLL_MODE scrollMode)
typedef void(CMPCALL * PFN_EVENT_SMS_STARTED)(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID SMSId)
typedef void(CMPCALL * PFN_EVENT_SUPPORTED_ORIENTATIONS_CHANGED)(HANDLE hCMP, CMPRESULT result, CMP_SUPPORTED_ORIENTATIONS supportedOrientation)
typedef void(CMPCALL * PFN_EVENT_USER_NOTIFIED)(HANDLE hCMP, CMPRESULT rc, CMP_UNIQUE_ID notificationId)
typedef void(CMPCALL * PFN_EVENT_VIDEO_CAPTURED)(HANDLE hCMP, CMPRESULT result, CMP_UNIQUE_LONG_ID uniqueId, UTF8_STRING videoMetadata, UTF8_STRING filename, UINT32 videoSize, const CMP_CAPTURE_VIDEO_OPTIONS *options)
typedef void(CMPCALL * PFN_EVENT_VIEWPORT_CHANGED)(HANDLE hCMP, CMPRESULT rc, INT16 flags, INT16 zoomFactor, INT32 x0Server, INT32 y0Server, INT32 x1Server, INT32 y1Server, INT32 x0Client, INT32 y0Client, INT32 x1Client, INT32 y1Client)
typedef void(CMPCALL * PFN_EVENT_VIEWPORT_ORIGIN_CHANGED)(HANDLE hCMP, CMPRESULT rc, INT32 left, INT32 top)
typedef INT16 INT32 INT32 pixelHeight
typedef INT16 INT32 pixelWidth
typedef char* UTF8_STRING
typedef INT16 INT32 INT32 INT16 INT32 INT32 CMP_ORIENTATION_POSITION INT32 WidthMilliInches
typedef INT16 INT32 INT32 INT16 INT32 XPixelsPerInch
typedef INT16 INT32 INT32 INT16 INT32 INT32 YPixelsPerInch

Function Documentation

void CMPCALL AppBackground ( HANDLE  hCMP)

Event: Application has background.

Parameters:
hCMPhandle to CMP object
void CMPCALL AppForeground ( HANDLE  hCMP)

Event: Application has foreground.

Parameters:
hCMPhandle to CMP object
void CMPCALL AudioCaptured ( HANDLE  hCMP,
CMPRESULT  result,
CMP_UNIQUE_LONG_ID  uniqueId,
UTF8_STRING  audioMetadata,
UTF8_STRING  filename,
INT32  audioSize,
const CMP_CAPTURE_AUDIO_OPTIONS options 
)

Event: Audio captured.

Parameters:
hCMPhandle to CMP object
resultresult of the audio capture request. if error, then the other parameters are not valid
uniqueIdunique id of the audio request
audioMetadatareturned audio metadata (including size and other interesting fields)
filenamelocation of the audio file
audioSizeThe size of the audio file in bytes.
optionsThe audio capture API uses fallback. So when the options you requested are not supported by the client device, it will automatically downgrade the request to use supported defaults. This options struct contains the option values that were used for the capture operation. You can compare them against your original request to determine if fallback was applied.
Examples:
native/captureaudio/captureaudio.cpp.
CMPAPIENTRY BSTRSafearrayToBSTR ( SAFEARRAY *  psa,
BSTR *  bstr 
)

Convert a BSTR Safearray to a single BSTR for use with multiple string support.

The resulting bstr needs to be freed with SysFreeString

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
psapointer to BSTR safearray
bstrreturned single BSTR (multiple BSTRs combined)
Returns:
CMPRESULT (CMP_ERROR_ID)
void CMPCALL ButtonPressed ( HANDLE  hCMP,
CMP_BUTTON_ID  buttonId 
)

Event: Device button was pressed.

Parameters:
hCMPhandle to CMP object
buttonIdbutton that was pressed
Examples:
native/redirectbutton/redirectbutton.cpp.
void CMPCALL ButtonTargetChanged ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_BUTTON_ID  buttonId,
CMP_BUTTON_TARGET  buttonTarget 
)

Event: Button target changed.

Parameters:
hCMPhandle to CMP object
rcresult of last request
buttonIdbutton identifier
buttonTargeteither client or host location
Examples:
native/redirectbutton/redirectbutton.cpp.
void CMPCALL CaptureMediaRemoved ( HANDLE  hCMP,
CMPRESULT  result,
CMP_UNIQUE_LONG_ID  captureId 
)

Event: capture media file has been removed from the mobile device.

Parameters:
hCMPhandle to CMP object
resultresult of the previous RemoveCaptureMedia request
captureIdthe Id of the capture media that was removed
void CMPCALL ChannelStateChanged ( HANDLE  hCMP,
CMP_CHANNEL_STATE  state 
)

Event: Channel state changed.

Parameters:
hCMPhandle to CMP object
statelatest state for the channel
CMPAPIENTRY CMPCaptureAudio ( HANDLE  hCMP,
const CMP_CAPTURE_AUDIO_OPTIONS options,
CMP_UNIQUE_LONG_ID audioId 
)

Capture a audio clip.

Options control how the audio clip is captured. There are options for limiting the storage size and the duration of time.

Execution: Async

Introduced: V2.0

Context: Remote

Foreground Required: Yes

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]optionsaudio options
[out]audioIdreturned unique picture Id
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/captureaudio/captureaudio.cpp.
CMPAPIENTRY CMPCapturePicture ( HANDLE  hCMP,
const CMP_CAPTURE_PICTURE_OPTIONS options,
CMP_UNIQUE_LONG_ID pictureId 
)

Capture a picture.

More options than TakePicture. Allows for reducing the size of the picture before transmitting to the server.

Execution: Async

Introduced: V2.0

Context: Remote

Foreground Required: Yes

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPHandle to CMP object
[in]optionsPicture options
[out]pictureIdReturned unique picture Id
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capturepicture/capturepicture.cpp.
CMPAPIENTRY CMPCaptureVideo ( HANDLE  hCMP,
const CMP_CAPTURE_VIDEO_OPTIONS options,
CMP_UNIQUE_LONG_ID videoId 
)

Capture a video clip.

Options control how the video is captured. There are options for limiting the storage size and the duration of time.

Execution: Async

Introduced: V2.0

Context: Remote

Foreground Required: Yes

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]optionsvideo options
[out]videoIdreturned unique picture Id
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capturevideo/capturevideo.cpp.
CMPAPIENTRY CMPClose ( HANDLE  hCMP)

Close Citrix mobile device object handle.

Close the mobile device handle and free any associated resources. Events handlers will no longer be notified once the handle is closed. Also, any calls to CMP API with the handle that was closed will fail.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpen

Related function: CMPOpen

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capabilities/capabilities.cpp, native/captureaudio/captureaudio.cpp, native/capturepicture/capturepicture.cpp, native/capturevideo/capturevideo.cpp, native/displaysettings/displaysettings.cpp, native/notifyuser/notifyuser.cpp, native/orientation/orientation.cpp, native/phonecall/phonecall.cpp, native/redirectbutton/redirectbutton.cpp, native/sendsms/sendsms.cpp, native/showkeyboard/showkeyboard.cpp, native/showpicker/showpicker.cpp, native/supportedorientations/supportedorientations.cpp, and native/takepicture/takepicture.cpp.
CMPAPIENTRY CMPCloseSession ( HANDLE  hCMP)

Close session connection.

Closes the current session with the mobile device. Each application can have its own session with the mobile device and closing the session will not have an effect on the other sessions.

Closing the session stops all the events from coming in. It also resets the state of the internal session object.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPOpenSession

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
Returns:
CMPRESULT CMP_ERROR_ID
Examples:
native/capabilities/capabilities.cpp, native/captureaudio/captureaudio.cpp, native/capturepicture/capturepicture.cpp, native/capturevideo/capturevideo.cpp, native/displaysettings/displaysettings.cpp, native/notifyuser/notifyuser.cpp, native/orientation/orientation.cpp, native/phonecall/phonecall.cpp, native/redirectbutton/redirectbutton.cpp, native/sendsms/sendsms.cpp, native/showkeyboard/showkeyboard.cpp, native/showpicker/showpicker.cpp, native/supportedorientations/supportedorientations.cpp, and native/takepicture/takepicture.cpp.
CMPAPIENTRY CMPDisableControls ( HANDLE  hCMP)

Disable Receiver controls.

Disable the Receiver controls from being used/displayed. This hides the receiver controls from view. Only the Apple iOS Receiver has a visible receiver control.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_RECEIVER_CONTROLS

Foreground Required: Yes

Requires: CMPOpenSession

Related Function: CMPGetControlsFlags CMPEnableControls

Related Event: ControlStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
Returns:
CMPRESULT CMP_ERROR_ID
CMPAPIENTRY CMPEnableControls ( HANDLE  hCMP)

Enable the Receiver Controls for use. Only the Apple iOS Receiver has a visible receiver control. This function makes the controls visible.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_RECEIVER_CONTROLS

Foreground Required: Yes

Requires: CMPOpenSession

Related Function: CMPDisableControls CMPGetControlsFlags

Related Event: ControlStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPFilterEvent ( HANDLE  hCMP,
CMP_EVENT_ID  eventId,
UINT16  filterFlags 
)

Filter specific events.

Filter event. By default, all registered events are reported to the application. There are times when the application needs to stop event notification but does not want to unregister the event handler.

CMP_EVENT_ID

filterFlags instructs the API to either turn filtering on or off.

Execution: Sync

Introduced: V1.0

Context: Local

Related Capability: CAPID_EVENT_FILTER

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPRegisterForEvent CMPUnregisterForEvent

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]eventIdevent identifier
[in]filterFlagsturn on/off event using flags CMP_FILTER_EVENT_DISABLE and CMP_FILTER_EVENT_ENABLE
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetAPIVersion ( HANDLE  hCMP,
CMP_VERSION cmpVersion 
)

Get CMP API Version.

The CMP SDK API is destined to change over time. This means that the API version should be checked before more recent features are used. It also helps to prove that the API meets a minimum level. The initial version of the Mobility Pack is 1.0. It was released to correspond to XenApp 6.5.

Two aspects of version are returned. The first part is the version of the CMP API. The second part is the file version information for CMPAPI and CMPCOM.

The things returned are:

API Version (Major, Minor) API Build Date

API DLL Name (CMPAPI.DLL for 32-bit, CMPAPI64.DLL for 64-bit) API DLL File Version (x.x.x.x)

COM DLL Name (CMPCOM.DLL for 32-bit, CMPCOM64.DLL for 64-bit) COM DLL File Version (x.x.x.x)

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpen

Related function: CMPGetDLLPath

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[out]cmpVersionreturns the requested versions from CMP
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetButtonTarget ( HANDLE  hCMP,
CMP_BUTTON_ID  buttonId,
CMP_BUTTON_TARGET buttonTarget 
)

Get button target.

Get the current destination for button events. The target will either be the server or the mobile device. The host application will be notified of button events if the server is the target and the application has registered for the ButtonPressed event. Otherwise the client (mobile device) will handle it like normal.

Currently only the BACK button is supported on the Android Receiver. The intent is to keep the button notification inside the server application so that the BACK button does not exit the session back to mobile receiver.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_BUTTON_SET_TARGET

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPSetButtonTarget

Related Event: ButtonTargetChanged ButtonPressed

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
[in]buttonIdbutton identification (home, search, back, etc.)
[out]buttonTargetpointer to destination for button events (server or client)
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetCapabilityBool ( HANDLE  hCMP,
CMP_CAP_ID  capId,
UINT16  keyId,
PBOOL  value 
)

Get capability boolean value.

Get a value for a specified capabilityId and keyId for a capability. Capabilities are used for determining what the mobile device and server agreed to for features. Usuallly it is just a indication of a specific feature set on the mobile device.

It is good practice to use the capability API to determine if the mobile device has certain features before trying to use them. It allows for a more dynamic application experience. For example, only certain types of mobile devices have certain features. A mobile phone has the ability to make phone calls, send SMS, and take pictures. A tablet might just have the ability to take pictures.

Capability values are negotiated during the connection of the virtual channel. Therefore, the values do not change during the session. It is sometimes mistaken that the capability display values are changing over time. It is better to use CMPGetDisplaySettings.

The capability Id is defined by CMP_CAP_ID.

The key Id is based on the capability selected. A list of possible key Ids are:

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPGetCapabilityInt16 CMPGetCapabilityUInt16 CMPGetCapabilityInt32 CMPGetCapabilityUInt32

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]capIdcapability category identification
[in]keyIdcapability key identification
[out]valuereturned boolean value
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capabilities/capabilities.cpp, and native/redirectbutton/redirectbutton.cpp.
CMPAPIENTRY CMPGetCapabilityInt16 ( HANDLE  hCMP,
CMP_CAP_ID  capId,
UINT16  keyId,
PINT16  value 
)

Get capability INT16 value.

Get a value for a specified capabilityId and keyId for a capability. Capabilities are used for determining what the mobile device and server agreed to for features. Usuallly it is just a indication of a specific feature set on the mobile device.

It is good practice to use the capability API to determine if the mobile device has certain features before trying to use them. It allows for a more dynamic application experience. For example, only certain types of mobile devices have certain features. A mobile phone has the ability to make phone calls, send SMS, and take pictures. A tablet might just have the ability to take pictures.

Capability values are negotiated during the connection of the virtual channel. Therefore, the values do not change during the session. It is sometimes mistaken that the capability display values are changing over time. It is better to use CMPGetDisplaySettings. The capability Id is defined by CMP_CAP_ID.

The key Id is based on the capability selected. A list of possible key Id are:

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPGetCapabilityBool CMPGetCapabilityUInt16 CMPGetCapabilityInt32 CMPGetCapabilityUInt32

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]capIdcapability category identification
[in]keyIdcapability key identification
[out]valuereturned value
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetCapabilityInt32 ( HANDLE  hCMP,
CMP_CAP_ID  capId,
UINT16  keyId,
PINT32  value 
)

Get capability INT32 value.

Get a value for a specified capabilityId and keyId for a capability. Capabilities are used for determining what the mobile device and server agreed to for features. Usuallly it is just a indication of a specific feature set on the mobile device.

It is good practice to use the capability API to determine if the mobile device has certain features before trying to use them. It allows for a more dynamic application experience. For example, only certain types of mobile devices have certain features. A mobile phone has the ability to make phone calls, send SMS, and take pictures. A tablet might just have the ability to take pictures.

Capability values are negotiated during the connection of the virtual channel. Therefore, the values do not change during the session. It is sometimes mistaken that the capability display values are changing over time. It is better to use CMPGetDisplaySettings.

The capability Id is defined by CMP_CAP_ID.

The key Id is based on the capability selected. A list of possible key Id are:

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPGetCapabilityBool CMPGetCapabilityInt16 CMPGetCapabilityUInt16 CMPGetCapabilityUInt32

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]capIdcapability category identification
[in]keyIdcapability key identification
[out]valuereturned value
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capabilities/capabilities.cpp.
CMPAPIENTRY CMPGetCapabilityUInt16 ( HANDLE  hCMP,
CMP_CAP_ID  capId,
UINT16  keyId,
PUINT16  value 
)

Get capability UINT16 value.

Get a value for a specified capabilityId and keyId for a capability. Capabilities are used for determining what the mobile device and server agreed to for features. Usuallly it is just a indication of a specific feature set on the mobile device.

It is good practice to use the capability API to determine if the mobile device has certain features before trying to use them. It allows for a more dynamic application experience. For example, only certain types of mobile devices have certain features. A mobile phone has the ability to make phone calls, send SMS, and take pictures. A tablet might just have the ability to take pictures.

Capability values are negotiated during the connection of the virtual channel. Therefore, the values do not change during the session. It is sometimes mistaken that the capability display values are changing over time. It is better to use CMPGetDisplaySettings.

The capability Id is defined by CMP_CAP_ID.

The key Id is based on the capability selected. A list of possible key Id are:

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPGetCapabilityBool CMPGetCapabilityInt16 CMPGetCapabilityInt32 CMPGetCapabilityUInt32

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]capIdcapability category identification
[in]keyIdcapability key identification
[out]valuereturned value
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capabilities/capabilities.cpp.
CMPAPIENTRY CMPGetCapabilityUInt32 ( HANDLE  hCMP,
CMP_CAP_ID  capId,
UINT16  keyId,
PUINT32  value 
)

Get capability UINT32 value.

Get a value for a specified capabilityId and keyId for a capability. Capabilities are used for determining what the mobile device and server agreed to for features. Usuallly it is just a indication of a specific feature set on the mobile device.

It is good practice to use the capability API to determine if the mobile device has certain features before trying to use them. It allows for a more dynamic application experience. For example, only certain types of mobile devices have certain features. A mobile phone has the ability to make phone calls, send SMS, and take pictures. A tablet might just have the ability to take pictures.

Capability values are negotiated during the connection of the virtual channel. Therefore, the values do not change during the session. It is sometimes mistaken that the capability display values are changing over time. It is better to use CMPGetDisplaySettings.

The capability Id is defined by CMP_CAP_ID.

The key Id is based on the capability selected. A list of possible key Id are:

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPGetCapabilityBool CMPGetCapabilityInt16 CMPGetCapabilityUInt16 CMPGetCapabilityInt32

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]capIdcapability category identification
[in]keyIdcapability key identification
[out]valuereturned value
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capabilities/capabilities.cpp.
CMPAPIENTRY CMPGetChannelState ( HANDLE  hCMP,
CMP_CHANNEL_STATE state 
)

Get the current channel state.

Determine the current channel state. This is useful for determining if channel is active. This value only reflects the state of the current process and not the session mobile receiver channel state. In other words, it reveals the local state of the virtual channel connection. Each process needs to bind to the shared virtual channel and go through a couple states before it can talk to the other side (mobile device).

  • CMP_CHANNEL_STATE_INITIAL Channel state when object first loaded
  • CMP_CHANNEL_STATE_CONNECTED Virtual channel has been connected
  • CMP_CHANNEL_STATE_DISCONNECTED Virtual channel is now disconnected
  • CMP_CHANNEL_STATE_BOUND Successful virtual channel negotiation
  • CMP_CHANNEL_STATE_BIND_FAILURE Binding stage has failed

INITIAL means that the state is initialized but the channel state is not yet determined. CONNECTED means that the virtual channel is open but has not been BOUND. DISCONNECTED means that the virtual channel has been closed. BOUND is the desired state since the channel is now ready for requests. BOUND implies that channel is fully operational. If the bind request fails, the state becomes BIND_FAILURE.

The typical transition is INITIAL -> CONNECTED -> BOUND. To get immediate notificiation of channel state changes, use the ChannelStateChanged event handler.

If the virtual channel is not enabled on the mobile receiver the typical transition is INITIAL -> CONNECTED -> BIND_FAILURE.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpen

Related Event: ChannelStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
[out]statestate (connected, disconnected, bound, etc...)
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetControlsFlags ( HANDLE  hCMP,
PUINT16  controlFlags 
)

Get Receiver controls flags.

Return the flags to show the state of the Receiver controls.

There is only one flag defined.

CMP_RECEIVER_CONTROLS_DISABLE = 0x0001

If the receiver controls are disabled, the flag will be on. If the receiver controls are enabled, the flag will be off.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_RECEIVER_CONTROLS

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPDisableControls CMPEnableControls

Related Event: ControlStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[out]controlFlagsreturned flags for controls
Returns:
CMPRESULT CMP_ERROR_ID
CMPAPIENTRY CMPGetDevicePropertyBool ( HANDLE  hCMP,
CMP_DEV_BOOL_PROP_ID  propertyId,
BOOL *  value 
)

Get device boolean property.

Gets a device property in boolean representation. The device properties are a collection of values that reveal what the device features are. The values do not change during the lifetime of a connection as they do not report on the state of the feature, only if it is present. E.g. if you query for CMP_DEVICE_BLUETOOTH this will return true if the phone supports bluetooth, regardless of whether it is on or off. However values may change when you roam a session to a different client device.

Examples:

  • CMP_DEVICE_3G = 0x1001 Supports 3G network
  • CMP_DEVICE_4G = 0x1002 Supports 4G network
  • CMP_DEVICE_ACCELEROMETER = 0x1003 Supports accelerometer
  • CMP_DEVICE_AUDIO_OUTPUT = 0x1004 Audio output
  • CMP_DEVICE_BATTERY = 0x1005 Battery present
  • CMP_DEVICE_BLUETOOTH = 0x1006 Bluetooth support
  • CMP_DEVICE_CAMERA = 0x1007 Camera

The full enumeration is available at CMP_DEV_BOOL_PROP_ID.

Each device property Id corresponds to a boolean value. The value is set to on if the feature is present.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_DEVICE_INFO

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPGetDevicePropertyString

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]propertyIddevice property id
[out]valuereturned boolean value
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetDevicePropertyString ( HANDLE  hCMP,
CMP_DEV_STRING_PROP_ID  propertyId,
UTF8_STRING  propertyString,
UINT32  propertyStringLen,
PUINT32  returnedSize 
)

Get device property string.

Get a string mobile device property setting. This is useful for determining more granular features and identifying the mobile device.

Examples:

CMP_DEVICE_MANUFACTURER = 0x0001 Mobile device manufacturer name CMP_DEVICE_MODEL = 0x0002 Mobile device model CMP_DEVICE_SERIAL_NUMBER = 0x0003 Mobile device serial number CMP_DEVICE_GIVEN_NAME = 0x0004 Given device name CMP_DEVICE_WIFI_MAC_ADDRESS = 0x0005 WiFi network MAC address CMP_DEVICE_BLUETOOTH_MAC_ADDRESS = 0x0006 Bluetooth network MAC address

The full enumeration is available at CMP_DEV_STRING_PROP_ID.

Each device property Id corresponds to a string value.

If the returned string is too large for the buffer, an error is returned and the returnedSize is set to the required buffer size. It is also possible to set the propertyString to NULL and the propertyStringLen to zero to request the size to correctly allocate the buffer.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_DEVICE_INFO

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPGetDevicePropertyBool

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]propertyIdunique property Id to get
[out]propertyStringbuffer used to return string
[in]propertyStringLenbuffer size
[out]returnedSizereturned size in bytes
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetDisplaySettings ( HANDLE  hCMP,
CMP_DISPLAY_SETTINGS dispSettings 
)

Get display settings.

Get the current display settings for the mobile device

  • Length Length of display settings structure
  • MetricsFlags Flags which define which structure fields are supported
  • DeviceOrientation Orientation of the device CMP_ORIENTATION_POSITION
  • PixelWidth Width in pixels of the mobile device display based on current orientation
  • PixelHeight Height in pixels of the mobile device display based on current orientation
  • ColorDepth Color bits used for each pixel for the mobile device display
  • WidthMilliInches Width of display in 1/1000th of an inch units (1000 = 1 inch)
  • HeightMilliInches Height of display in 1/1000th of an inch units (1000 = 1 inch)
  • PixelsPerInch Pixels per inch combined between vertical and horizontal
  • HorizontalPixelsPerInch Pixels per inch along the horizontal
  • VerticalPixelsPerInch Pixels per inch along the vertical

MetricsFlags indicates which of the following fields are valid. Width and height change based on orientation. The current orientation determines the PixelsPerInch for horizontal and vertical.

The display settings can change over time besides just orientation changes. It is best to be notified of changes using the DisplaySettingsChanged event.

Pixel width and height represents the physical screen dimensions. In order to discover the section of the screen that can be used by the application, you need to use CMPGetViewport instead.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_DISPLAY_INFO

Foreground Required: No

Requires: CMPOpenSession

Related Event: DisplaySettingsChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[out]dispSettingsdisplay settings
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/displaysettings/displaysettings.cpp.
CMPAPIENTRY CMPGetDLLPath ( HANDLE  hCMP,
LPCSTR  DLLfilename,
LPSTR  DLLfilepath,
UINT32  pathLength 
)

Get DLL Path for a given CMP-related DLL name.

For a given Windows machine, it can be difficult to determine which DLL is loaded. This function returns the path that is currently being used. It is necessary to do a CMPOpen first to load the modules in memory. It also is recommended to use CMPGetAPIVersion to determine the DLL file names.

For standard DLLs like CMPAPI.DLL, the load location is first determined using the standard search path.

From Microsoft documentation:

  • The directory from which the application loaded.
  • The system directory. Use the GetSystemDirectory function to get the path of this directory.
  • The 16-bit system directory. There is no function that obtains the path of this directory, but it is searched.
  • The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.
  • The current directory.
  • The directories that are listed in the PATH environment variable.

For COM DLLs like CMPCOM.DLL, the file location is determined by the COM registration in the registry.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpen

Related function: CMPGetAPIVersion

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]DLLfilenamename of the CMP DLL to get the path for
[out]DLLfilepathresulting DLL path
[in]pathLengthlength of the path buffer
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetKeyboardState ( HANDLE  hCMP,
CMP_KEYBOARD_STATE kybdState 
)

Get keyboard state.

Get the current keyboard state. The keyboard has a number of different aspects associated with it.

CMP_KEYBOARD_TYPE selects the style of keyboard used. The keyboard types supported can be derived from the capabilities. Android only supports the standard ones while iOS has a larger variety. Probably the most obvious difference is between a standard keyboard and a numeric pad.

CMP_KEYBOARD_FLAGS reveal the current state of the keyboard.

  • CMP_KYBD_FLAG_PHYSICAL Physical keyboard available (readonly)
  • CMP_KYBD_FLAG_VISIBLE Display keyboard visible (readonly)
  • CMP_KYBD_FLAG_EXT_FLAG Extended kebyoard
  • CMP_KYBD_FLAG_USE_RECT Use rectangle co-ordinates for viewing section of display
  • CMP_KYBD_FLAG_AUTO_CORRECT Auto correct text
  • CMP_KYBD_FLAG_AUTO_CAPITAL Auto-capitalize text
  • CMP_KYBD_FLAG_RETURN_KEY_TYPE Return key text to show

The first two fields can only be retrieved. It is unlikely that the device has a physical keyboard attached but the CMP_KYBD_FLAG_PHYSICAL will be set if there is one there. If the on-screen keyboard is visible, the CMP_KYBD_FLAG_VISIBLE flag will be on. The on-screen keyboard can have extended keys like Tab, Esc, Del, Page Up, Page Down, Home, End, Cut, Copy, Paste, and Alt+Tab. These keys can be used to better control programs that expect these keys to be available. The CMP_KYBD_FLAG_EXT_FLAG indicates that these keys are present.

The remaining flags indicate the use of certain features.

  • Edit area location
  • Auto correct
  • Auto capitalization
  • Return key customization

If the bit is on for the USE_RECT, it means that the rectangle coordinates are valid and can be used for selecting which part of the server screen is visible. It is useful to have the text area on the screen as the user types the keys in. The program needs to gather and setthe rectangle coordinates before showing the keyboard and set the CMP_KYBD_FLAG_USE_RECT flag.

On iOS devices, it is possible to configure auto correction and capitalization. It also possible to specify a different return key label. These aspects are only enabled if the flags are set.

Capabilities reveal what is available. Check CMP_CAP_INPUT_KEY_ID for possible features.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_INPUT

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPShowKeyboard CMPHideKeyboard

Related Event: KeyboardStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[out]kybdStatekeyboard selection and other keyboard settings
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetOrientation ( HANDLE  hCMP,
CMP_ORIENTATION_DATA orientationData 
)

Get orientation.

Get the current orientation data (application and device orientation, orientation flags) from the mobile device. Device orientation can be different from application orientation based on the orientation flags. If the orientation flags indicate that the application orientation is locked, then the device orientation can change and be different from application orientation. If the orientation flags indicate follow mode then the two orientation values will be the same regardless of orientation position.

CMP_ORIENTATION_POSITION values

  • CMP_ORIENTATION_UNKNOWN = 0x0000
  • CMP_ORIENTATION_PORTRAIT = 0x0001
  • CMP_ORIENTATION_PORTRAIT_UPSIDE_DOWN = 0x0002
  • CMP_ORIENTATION_LANDSCAPE_LEFT = 0x0003
  • CMP_ORIENTATION_LANDSCAPE_RIGHT = 0x0004

CMP_ORIENTATION_FLAG values

  • CMP_ORIENTATION_FLAG_LOCK = 0x0001
  • CMP_ORIENTATION_FLAG_FOLLOW_SENSOR = 0x0002

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_ORIENTATION

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPSetOrientation

Related Event: OrientationChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[out]orientationDatacontains the relevant orientation data
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/orientation/orientation.cpp.
CMPAPIENTRY CMPGetPickerState ( HANDLE  hCMP,
CMP_UNIQUE_ID  controlId,
PUINT16  pickerState 
)

Get current picker control state.

Get the picker control state on the mobile device. The intent of this API is to provide the program with information about a particular picker control. This includes being able to determine if the control is visible, has been cancelled, or an item has been selected. It will only return information for an existing picker control and will return an error for an invalid picker control identification. The picker control state is arranged in bit flags which makes it possible to have them be combined. In reality, these flags are independent of each other. If the control is visible, selection has not happened yet and neither has it been cancelled. Once a selection is made, the picker control is no longer visible. When the picker control is cancelled, it is not selected and also not visible.

CMP_PICKER_CONTROL_STATE

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_PICKER_CONTROL

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPShowPickerUTF16 CMPShowPicker CMPHidePicker

Related Event: PickerControlStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]controlIdpicker control identifier
[out]pickerStatereturned picker state CMP_PICKER_CONTROL_STATE
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetPictureFilename ( HANDLE  hCMP,
CMP_UNIQUE_ID  pictureId,
UTF8_STRING  filename,
UINT32  bufferLength,
PUINT32  returnedLength 
)

Get the name of the picture file.

Translate the pictureId into the actual file location which can be accessed by the application on the host. The picture is accessed using standard file operations. The picture file is transferred using Client Drive Mapping (CDM).

It is very important to make sure the Android mobile receiver has allowed access to the SD card (read or full). Otherwise it is not possible to take pictures and download them. It is also important to allow CDM for the user's session.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_TAKE_PICTURE

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPTakePicture CMPGetPictureState CMPRemovePicture

Related Events: PictureTaken

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]pictureIdunique picture identifier
[out]filenamereturned filename for picture
[in]bufferLengthlength of the filename buffer
[out]returnedLengthlength of filename returned
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetPictureState ( HANDLE  hCMP,
CMP_UNIQUE_ID  pictureId,
PUINT32  size,
CMP_PICTURE_STATE pictState 
)

Get picture state.

Get the picture state from the mobile device camera. This could be used to poll the status of the camera after taking a picture. An alternative is to use the events related to the picture being taken.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_TAKE_PICTURE

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPGetPictureFilename CMPRemovePicture CMPTakePicture

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]pictureIdunique picture identifier
[out]sizereturned size of picture
[out]pictStatereturned state of the picture (downloading, downloaded)
Returns:
CMPRESULT
CMPAPIENTRY CMPGetScrollMode ( HANDLE  hCMP,
CMP_SCROLL_MODE scrollMode 
)

Get scroll mode.

Get the current scroll mode from the mobile device.

Scroll modes:

  • CMP_SCROLLMODE_MOUSEWHEEL = 0x0001
  • CMP_SCROLLMODE_DRAG = 0x0002
  • CMP_SCROLLMODE_PAN = 0x0003

Receivers with full support for Citrix Mobility Pack can use one of three different input modes which you can programmatically set from your app using CMP. The first two were designed for interacting with legacy Windows apps, and the third mode was one we added with CMP which works better for apps designed for mobile platforms.

  • CMP_SCROLLMODE_PAN Panning Mode: This is for when the session size is bigger than the size of the clients screen. So in order to view all of the app inside the session you need a way to pan the viewport around. Swipes in panning mode will move the viewport around. Pinch gestures in this mode are also supported and they allow you to zoom in/out.
  • CMP_SCROLLMODE_MOUSEWHEEL Scrolling or Mouse Scroll Wheel mode: Vertical swipes get turned into mouse wheel scroll messages. Horizontal swipes get turned into left/right arrow key presses (this was added to trigger PowerPoint navigation).
  • CMP_SCROLLMODE_DRAG Drag or Raw Input mode: all touch input is turned into raw mouse input. Taps become left mouse click messages, and drags become mouse move messages. This is the simplest mode as it does no gesture translation and gives the server the most flexibility for doing it's own input processing.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_SCROLL_MODES

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPSetScrollMode

Related Event: ScrollModeChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[out]scrollModereturned scroll mode
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetSessionOptionBool ( HANDLE  hCMP,
CMP_SESSION_OPTION  option,
BOOL *  value 
)

Get boolean session option.

Returns the current setting for the requested session option.

There are only two options available currently:

  • CMP_SESSION_OPTION_IGNORE_FOREGROUND_CHECK
  • CMP_SESSION_OPTION_DISABLE_CACHE

CMP_SESSION_OPTION_IGNORE_FOREGROUND_CHECK controls whether or not the API enforces a foreground check. This option is FALSE by default. Some API should only be called while the application is in the foreground. Some API will reject certain calls if they are called in the background. Setting this option to TRUE will disable the foreground check and make it possible for the program to call any of the API regardless of the foreground/background status.

CMP_SESSION_OPTION_DISABLE_CACHE controls whether or not the mobile device values will be cached. Caching is on by default. In some cases it might be better to turn off caching. This means that requests to get values will go directly to the mobile device instead of using the cache.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPSetSessionOptionBool

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
[in]optionsession option
[out]valuereturned boolean session option value
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetSessionState ( HANDLE  hCMP,
CMP_SESSION_STATE sessionState 
)

Get the current session state.

Determine what the current session state is. This is useful for determining if connected or disconnected.

  • CMP_SESSION_STATE_INITIAL = 0
  • CMP_SESSION_STATE_CONNECTED = 1
  • CMP_SESSION_STATE_DISCONNECTED = 2
  • CMP_SESSION_STATE_LOCKED = 3
  • CMP_SESSION_STATE_UNLOCKED = 4
  • CMP_SESSION_STATE_LOGGED_ON = 5
  • CMP_SESSION_STATE_LOGGED_OFF = 6
  • CMP_SESSION_STATE_CONSOLE = 7

The three most important values are INITIAL, CONNECTED, and DISCONNECTED. Only XenDesktop supports LOCKED and UNLOCKED. It is unlikely that the program could ever be notified of LOGGED_ON or LOGGED_OFF. CONSOLE is only possible for non-remote sessions.

INITIAL means that the session state is not yet determined. CONNECTED means that the session is remotely connected to a device. DISCONNECTED means that the session was CONNECTED but has lost the connection.

A better way to be notified of session state changes is to register an event handler for SessionStateChanged.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpen

Related Event: SessionStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
[out]sessionStatesession state (connected, disconnected, locked, unlocked, etc...)
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetSupportedOrientations ( HANDLE  hCMP,
CMP_SUPPORTED_ORIENTATIONS supportedOrientations 
)

Get which orientations the application is going to support.

If the application has never set which applications are supported, it will most likely get all orientations are supported unless the device does not support some orientations.

Execution: Sync

Introduced: V2.0

Context: Remote

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[out]supportedOrientationsorientations supported by the application
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/supportedorientations/supportedorientations.cpp.
CMPAPIENTRY CMPGetViewport ( HANDLE  hCMP,
INT16 *  flags,
INT16 *  zoomFactor,
CMP_DISPLAY_RECT serverViewport,
CMP_DISPLAY_RECT clientViewport 
)

Get viewport.

Get the server and client viewports

In order to understand where the application is being displayed, it is important to gather the viewport and zoom information.

The flags indicate which fields are valid.

CMP_VIEWPORT_VALID_FLAGS

  • CMP_VIEWPORT_VALID_FLAG_ZOOM_FACTOR = 0x0001 Zoom factor is valid
  • CMP_VIEWPORT_VALID_FLAG_SERVER_VIEWPORT = 0x0002 Server viewport is valid
  • CMP_VIEWPORT_VALID_FLAG_CLIENT_VIEWPORT = 0x0004 Client viewport is valid

There is a reason why there are two viewports.

  • Server viewport
  • Client viewport

The server viewport is the dimensions of the visible server window rectangle. It is expressed in server coordinates. Think of it as selecting a part of the server display screen. It can be changed with CMPSetViewport.

The client viewport is the rectangle that reveals what can be displayed on the client. The client viewport is more than a window area. The client viewport indicates how much of the client can be drawn. Some devices have display bars at the top and/or bottom and this restricts how much the application can show. Status bars are the most common display bar.

Without knowledge of the client viewport, the application is blind to how much of the display area can be used. It is possible to get the display settings CMPGetDisplaySettings but the width and height do not exclude the built-in system display bars.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_VIEWPORT

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPSetViewport CMPGetViewportOrigin CMPSetViewportOrigin

Related Event: ViewportChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[out]flagsindicate which fields have been returned CMP_VIEWPORT_VALID_FLAGS
[out]zoomFactoramount of zoom being used (100 = 1x, 200 = 2x)
[out]serverViewportrectangle that specifies coordinates of server viewport in server coordinate framework
[out]clientViewportrectangle that specifies coordinates of client viewport in client coordinate framework
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPGetViewportOrigin ( HANDLE  hCMP,
CMP_DISPLAY_POINT pt 
)

Get viewport origin.

Get the origin of the Citrix Receiver viewport.

CMP_DISPLAY_POINT

  • Left x coordinate
  • Top y coordinate

The viewport origin is the top left corner of viewport into the server application. Typically it is (0,0) but change be changed by user action or CMPSetViewportOrigin.

The server application can use the viewport origin to select what part of the application is currently visible.

Execution: Sync

Introduced: V1.0

Context: Remote

Result Data Cached: Yes

Related Capability: CAPID_VIEWPORT

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPSetViewportOrigin CMPSetViewport CMPGetViewport

Related Event: ViewportOriginChanged ViewportChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[out]ptLocation of the position of the viewport (top, left)
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPHideKeyboard ( HANDLE  hCMP)

Hide display keyboard.

Hide the display keyboard. If it is necessary to check first, use CMPGetKeyboardState.

Execution: Async

Introduced: V1.0

Related Capability: CAPID_INPUT

Context: Remote

Foreground Required: Yes

Requires: CMPOpenSession

Related Function: CMPShowKeyboard CMPGetKeyboardState

Related Event: KeyboardStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPHidePicker ( HANDLE  hCMP,
CMP_UNIQUE_ID  controlId 
)

Hide picker control.

Hide a picker control that is currently being displayed. The picker control is automatically hidden when the user either cancels (touchs outside the picker or hits the back button) or selects an item in the picker control. However, the application might want to hide the picker control before the user has done something with it. This could be true in the case where the user has walked away from the device and it is idle for some time. Or perhaps the application has a change and has decided that it does not need to know this anymore.

The picker control identification (controlId) is unique to this picker control and was used by the CMPShowPicker function. The application selects the controlId based on its own rules.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_PICKER_CONTROL

Foreground Required: Yes

Requires: CMPOpenSession

Related Functions: CMPShowPickerUTF16 CMPShowPicker CMPGetPickerState

Related Event: PickerControlStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]controlIdpicker control identifier
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPInitialize ( BOOL  MultiThreadedApartment)

Initialize COM for CMP.

Need to have COM initialized in order for CMPAPI to work

It is a requirement that Microsoft COM be initialized before calling CMPOpen. Either use CMPInitialize or CoInitialize to intialize COM for each thread calling CMP API. If you are not already using COM, using CMPInitialize is preferred. Be sure to pair every call to CMPInitialize with a call to CMPUninitialize. You only need to initialize COM once per thread. COM is used as the core framework of how CMP API calls are supported. You do not need to worry about how COM works in order to use the API but you still need to make sure that COM is initialized with CMPInitialize.

With MultiThreadedApartment, it specifies whether the COM model is STA or MTA. STA is automatically thread safe but can lead to bottlenecks. MTA allows more to happen at once and direct calls but might need to be protected with synchronization. The CMP model allows for either.

If unsure which to use, STA is safer. However, STA requires a Windows message loop to process incoming requests.

Execution: Sync

Introduced: V1.0

Context: Local

Related Function: CMPUninitialize

Foreground Required: No

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]MultiThreadedApartment
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capabilities/capabilities.cpp, native/captureaudio/captureaudio.cpp, native/capturepicture/capturepicture.cpp, native/capturevideo/capturevideo.cpp, native/displaysettings/displaysettings.cpp, native/notifyuser/notifyuser.cpp, native/orientation/orientation.cpp, native/phonecall/phonecall.cpp, native/redirectbutton/redirectbutton.cpp, native/sendsms/sendsms.cpp, native/showkeyboard/showkeyboard.cpp, native/showpicker/showpicker.cpp, native/supportedorientations/supportedorientations.cpp, and native/takepicture/takepicture.cpp.
CMPAPIENTRY CMPNotifyUser ( HANDLE  hCMP,
CMP_UNIQUE_ID  notificationId,
USHORT  notificationFlags,
UTF8_STRING  notificationText 
)

Notify user of event.

Notify the user of an event using a combination of vibration, sound, light, and text. This is similar to being notified of an incoming SMS message. The program selects the combination of which notification types it wants. Each method of notification is optional. For example, it is possible to vibrate the mobile device without sending text. The notification flags indicate which means to use.

CMP_NOTIFICATION_FLAGS

  • CMP_NOTIFICATION_FLAG_LIGHT =0x0001 Light notification
  • CMP_NOTIFICATION_FLAG_VIBRATE =0x0002 Vibrate
  • CMP_NOTIFICATION_FLAG_AUDIO =0x0004 Audio
  • CMP_NOTIFICATION_FLAG_TEXT =0x0008 Text
  • CMP_NOTIFICATION_ALL_FLAGS =0x000F All notification flags

Notification types

  • Vibration - the device buzzes
  • Sound - the device makes a noise based on a default selection
  • Light - the device flashes
  • Text - message is displayed

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_NOTIFICATION

Foreground Required: Yes

Requires: CMPOpenSession

Related Event: UserNotified

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]notificationIdnotification identifier
[in]notificationFlagscontrols which options are used
[in]notificationTexttext to display (if notification flag for text is set)
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/notifyuser/notifyuser.cpp.
CMPAPIENTRY CMPOpen ( HANDLE *  phCMP)

Create Citrix mobile device object and return a handle.

It is a requirement that Microsoft COM be initialized before calling CMPOpen. Either use CMPInitialize or CoInitialize to intialize COM for each thread calling CMP API. If you are not already using COM, using CMPInitialize is preferred. Be sure to pair every call to CMPInitialize with a call to CMPUninitialize. You only need to initialize COM once per thread. COM is used as the core framework of how CMP API calls are supported. You do not need to worry about how COM works in order to use the API but you still need to make sure that COM is initialized with CMPInitialize.

The returned handle is used for all future CMP-related calls. It is allowed to have multiple CMP handles per thread. The handle is also passed to the event handlers once the events are registered and events are triggered. Communication with the mobile device will only happen once CMPOpenSession is called successfully. Once the program is about to exit or terminate the connection, it should call CMPClose to release resources.

Execution: Sync

Context: Local

Foreground Required: No

Requires: CMPInitialize

Related function: CMPClose

Introduced: V1.0

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[out]phCMPpointer to CMP Object handle (returned on successful completion)
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capabilities/capabilities.cpp, native/captureaudio/captureaudio.cpp, native/capturepicture/capturepicture.cpp, native/capturevideo/capturevideo.cpp, native/displaysettings/displaysettings.cpp, native/notifyuser/notifyuser.cpp, native/orientation/orientation.cpp, native/phonecall/phonecall.cpp, native/redirectbutton/redirectbutton.cpp, native/sendsms/sendsms.cpp, native/showkeyboard/showkeyboard.cpp, native/showpicker/showpicker.cpp, native/supportedorientations/supportedorientations.cpp, and native/takepicture/takepicture.cpp.
CMPAPIENTRY CMPOpenForProcess ( HANDLE *  phCMP,
DWORD  processId 
)

Create Citrix mobile device object for a specific process and return a handle.

It is a requirement that Microsoft COM be initialized before calling CMPOpenForProcess. Either use CMPInitialize or CoInitialize to intialize COM for each thread calling CMP API. If you are not already using COM, using CMPInitialize is preferred. Be sure to pair every call to CMPInitialize with a call to CMPUninitialize. You only need to initialize COM once per thread. COM is used as the core framework of how CMP API calls are supported. You do not need to worry about how COM works in order to use the API but you still need to make sure that COM is initialized with CMPInitialize.

The returned handle is used for all future CMP-related calls. It is allowed to have multiple CMP handles per thread. The handle is also passed to the event handlers once the events are registered and events are triggered. Communication with the mobile device will only happen once CMPOpenSession is called successfully. Once the program is about to exit or terminate the connection, it should call CMPClose to release resources.

Execution: Sync

Context: Local

Foreground Required: No

Requires: CMPInitialize

Related function: CMPClose

Introduced: V2.0

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[out]phCMPPointer to CMP Object handle (returned on successful completion)
[in]processIdThe PID of the process you want to open a Citrix mobile device object for.
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPOpenSession ( HANDLE  hCMP)

Open session connection.

Opens a session with the mobile device. Each application can have its own session and opening the session will not have an effect on the other sessions. The session is needed before any requests are made to the mobile device.

It is unnecessary to call CMPOpenSession before using functions that require a session. Each function that requires an active session automatically calls the equivalent of CMPOpenSession so that it will be in the correct state before the request is generated.

Internally, this function starts communication with a service which in turn connects to the mobile device (Mobile Receiver). At the time of this writing, only Android and iOS (Apple) are supported. The Mobile Receiver needs the MRVC virtual channel in order to support Citrix Mobility Pack.

The most common failure for this function is when the Receiver does not support MRVC. For example, the Windows Receiver has no MRVC support.

Required Receiver minimum versions:

CMP Version 1.0 Citrix Android Receiver 3.0 (late 2011) Citrix iOS Receiver 5.5 (early 2012)

CMP Version 2.0 Citrix Android Receiver 3.4 (mid 2013) Citrix iOS Receiver 5.8 (mid 2013)

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpen

Related Function: CMPCloseSession

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/capabilities/capabilities.cpp, native/captureaudio/captureaudio.cpp, native/capturepicture/capturepicture.cpp, native/capturevideo/capturevideo.cpp, native/displaysettings/displaysettings.cpp, native/notifyuser/notifyuser.cpp, native/orientation/orientation.cpp, native/phonecall/phonecall.cpp, native/redirectbutton/redirectbutton.cpp, native/sendsms/sendsms.cpp, native/showkeyboard/showkeyboard.cpp, native/showpicker/showpicker.cpp, native/supportedorientations/supportedorientations.cpp, and native/takepicture/takepicture.cpp.
CMPAPIENTRY CMPProcessDetect ( HANDLE  hCMP,
DWORD  processId,
PBOOL  detectFlag 
)

Detect if a process is using the Citrix Mobility Pack.

During the development of CMP, it became necessary to know whether or not a process was hosting the CMP object. This was needed to avoid the automatic features from altering the process that already handles things using the CMP SDK API.

In general it is not necessary to know about this feature. The reason is that the COM object will automatically register the running process. However, if the process launches another program, it will need to register that process if it does not use CMP directly.

To explain this from a completely different angle, registering with CMP is important to stop any kind of automatic processing. For example, the CMP includes code to automatically convert combo boxes into picker controls. It also has the ability to automatically popup a on-screen keyboard. These features are useful for legacy programs that are unaware of the mobile device features.

Applications that are aware of CMP do not need this. They can manage on their own and do want any kind of outside assistance. Even programs that are not using CMP directly could benefit from not being automatically handled. An example of this is a helper reader program that is read-only and does not need the keyboard popup. This was discovered during the development of Project GoldenGate for the sake of launching helper applications for attachments.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpen

Related Functions: CMPRegisterProcess CMPUnregisterProcess

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]processIdprocess Id of the process to be checked
[out]detectFlagindicates if it is using CMP (TRUE) or it is a legacy application (FALSE)
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPRegisterForEvent ( HANDLE  hCMP,
CMP_EVENT_ID  eventId,
CMP_EVENT_CALLBACK  eventHandler 
)

Register event handler.

Register for event notification. Only allowed once for a given event.

CMP_EVENT_ID

Version 1 Events:

Version 2 Events:

The protocols of the event handlers has to match the ones defined in cmp.h.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPFilterEvent CMPUnregisterForEvent

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]eventIdevent identifier
[in]eventHandlerevent handler function
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/captureaudio/captureaudio.cpp, native/capturepicture/capturepicture.cpp, native/capturevideo/capturevideo.cpp, native/displaysettings/displaysettings.cpp, native/notifyuser/notifyuser.cpp, native/orientation/orientation.cpp, native/phonecall/phonecall.cpp, native/redirectbutton/redirectbutton.cpp, native/sendsms/sendsms.cpp, native/showkeyboard/showkeyboard.cpp, native/showpicker/showpicker.cpp, native/supportedorientations/supportedorientations.cpp, and native/takepicture/takepicture.cpp.
CMPAPIENTRY CMPRegisterProcess ( HANDLE  hCMP,
DWORD  processId 
)

Register a process for Citrix Mobility Pack.

Sometimes it is necessary to label a process as using CMP even though it might not be using it directly. This API creates a marker that exists until the process is unregistered with CMPUnregisterProcess.

The most common use case for registering processes is having a parent application that uses worker processes. If the parent is aware of Citrix Mobility Pack but the children are not, the parent might still want to stop the child processes from using the automatic mobile device features (auto keyboard and auto combobox).

The registration of the process continues until the process that created the marker is exited or the marker is unregistered.

It is not allowed to register for non-existing process Ids. It is okay to register a process that is already registered. Calling Register and Unregister should be paired accurately. The marker is reference counted so that means that when the final unregister happens, the marker will be removed.

It is important to track the life of the process. If the process exits early or unexpectantly, the parent will have to monitor that situation and unregister the process. Otherwise, a new process could start with the same process identifier and the existing marker would make it look like a CMP process. This would block the automatic mobile device features for that process.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpen

Related Functions: CMPProcessDetect CMPUnregisterProcess

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]processIdprocess Id of the process to be registered
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPRemoveCapturedData ( HANDLE  hCMP,
CMP_UNIQUE_LONG_ID  captureId 
)

Remove the files associated with the original capture.

Delete the associated files on the device based on the captureId.

Execution: Async

Introduced: V2.0

Context: Remote

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPHandle to CMP object
[in]captureIdCaptured data identifier
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/captureaudio/captureaudio.cpp, native/capturepicture/capturepicture.cpp, and native/capturevideo/capturevideo.cpp.
CMPAPIENTRY CMPRemovePicture ( HANDLE  hCMP,
CMP_UNIQUE_ID  pictureId 
)

Remove picture.

Remove the picture from the mobile device. When the picture is no longer needed then there is no reason to keep it on the device. This function only works with images that were taken with CMPTakePicture. The pictureId is required to identify the picture. The mobile device will not delete a picture until it is told to remove it.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_TAKE_PICTURE

Foreground Required: No

Requires: CMPOpenSession CMPTakePicture

Related Function: CMPGetPictureFilename CMPGetPictureState CMPTakePicture

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]pictureIdunique picture identifier
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPSendSMS ( HANDLE  hCMP,
UTF8_STRING  phoneNumber,
CMP_UNIQUE_ID  msgId,
UTF8_STRING  SMSText 
)

Send SMS.

Send a SMS message using the mobile device. The msgId is used to track the SMS request. When the request is made to the mobile device, the SMS application is started. The phone number and SMS text are optional. However, if they are specified, the SMS application will include the text and phone number specified.

For security reasons, the SMS is not sent automatically. The user has to indicate it is okay to send the message.

The phone number is not restricted to specific characters so it is possible to specify text as well as numbers.

The text is based on UTF-8 which allows for all Unicode characters. If it is concern to change Windows Unicode to UTF-8, use the CMP API for converting.

The msgId (CMP_UNIQUE_ID) is specified in the resulting event SMSStarted. Be sure to match the Id to confirm the original request. The result from CMPSendSMS does not indicate whether or not the mobile device received the request. In order to confirm arrival of the request, the SMSStarted event should be registered.

Even if the SMSStarted event succeeds, it cannot be confirmed that the SMS message was sent to the other party. The user could cancel the SMS application send request or the mobile network could fail to deliver the message.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_SMS

Foreground Required: Yes

Requires: CMPOpenSession

Related Event: SMSStarted

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]phoneNumberphone number for destination
[in]msgIdmessage identifier
[in]SMSTexttext to send with the SMS
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/sendsms/sendsms.cpp.
CMPAPIENTRY CMPSetButtonTarget ( HANDLE  hCMP,
CMP_BUTTON_ID  buttonId,
CMP_BUTTON_TARGET  buttonTarget 
)

Set button target.

Set the destination for button events. The target will either be the server or the mobile device. The host application will be notified of button events if the server is the target and the application is registered to handle ButtonPressed events. Otherwise the mobile device will handle it.

Currently only the BACK button is supported on the Android Receiver. The intent is to keep the button notification inside the server application so that the BACK button does not exit the session back to mobile receiver.

Care should be taken to restore button redirection before the program completes. It is a known issue (Redirect Button) and unexpected results will happen if the "back" button is not restored to select the moble device (client).

Execution: Async

Introduced: V1.0

Context: Remote

Foreground Required: Yes

Related Capability: CAPID_BUTTON_SET_TARGET

Requires: CMPOpenSession

Related function: CMPGetButtonTarget

Related Event: ButtonTargetChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
[in]buttonIdbutton identification (home, search, back, etc.)
[in]buttonTargetdestination for button events (server or client)
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/redirectbutton/redirectbutton.cpp.
CMPAPIENTRY CMPSetOrientation ( HANDLE  hCMP,
CMP_ORIENTATION_POSITION  orientation,
UINT16  orientationFlags 
)

Set orientation.

Set the application orientation and orientation flags for the mobile device. Device and application orientation can be different based on the orientation flags.

CMP_ORIENTATION_POSITION values

  • CMP_ORIENTATION_UNKNOWN = 0x0000
  • CMP_ORIENTATION_PORTRAIT = 0x0001
  • CMP_ORIENTATION_PORTRAIT_UPSIDE_DOWN = 0x0002
  • CMP_ORIENTATION_LANDSCAPE_LEFT = 0x0003
  • CMP_ORIENTATION_LANDSCAPE_RIGHT = 0x0004

CMP_ORIENTATION_FLAG values

  • CMP_ORIENTATION_FLAG_LOCK = 0x0001
  • CMP_ORIENTATION_FLAG_FOLLOW_SENSOR = 0x0002

If the "FOLLOW_SENSOR" flag is selected, then it is not important what the ORIENTATION_POSITION is set to. This is because the orientation position will automatically be set to the current device orientation.

It does not make sense to set both orientation flags on.

"LOCK" will set the orientation to the specified position and keep it that way regardless of device orientation.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_ORIENTATION

Foreground Required: Yes

Requires: CMPOpenSession

Related Function: CMPGetOrientation

Related Event: OrientationChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]orientationcontains the relevant orientation data
[in]orientationFlagscontrols the orientation to either be "follow" or "locked"
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/orientation/orientation.cpp.
CMPAPIENTRY CMPSetScrollMode ( HANDLE  hCMP,
CMP_SCROLL_MODE  scrollMode 
)

Set scroll mode.

Set the scroll mode for the mobile device.

Scroll modes:

  • CMP_SCROLLMODE_MOUSEWHEEL = 0x0001
  • CMP_SCROLLMODE_DRAG = 0x0002
  • CMP_SCROLLMODE_PAN = 0x0003

Receivers with full support for Citrix Mobility Pack can use one of three different input modes which you can programmatically set from your app using CMP. The first two were designed for interacting with legacy Windows apps, and the third mode was one we added with CMP which works better for apps designed for mobile platforms.

  • CMP_SCROLLMODE_PAN Panning Mode: This is for when the session size is bigger than the size of the clients screen. So in order to view all of the app inside the session you need a way to pan the viewport around. Swipes in panning mode will move the viewport around. Pinch gestures in this mode are also supported and they allow you to zoom in/out.
  • CMP_SCROLLMODE_MOUSEWHEEL Scrolling or Mouse Scroll Wheel mode: Vertical swipes get turned into mouse wheel scroll messages. Horizontal swipes get turned into left/right arrow key presses (this was added to trigger PowerPoint navigation).
  • CMP_SCROLLMODE_DRAG Drag or Raw Input mode: all touch input is turned into raw mouse input. Taps become left mouse click messages, and drags become mouse move messages. This is the simplest mode as it does no gesture translation and gives the server the most flexibility for doing it's own input processing.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_SCROLL_MODES

Foreground Required: Yes

Requires: CMPOpenSession

Related Function: CMPGetScrollMode

Related Event: ScrollModeChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]scrollModescroll mode
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPSetSessionOptionBool ( HANDLE  hCMP,
CMP_SESSION_OPTION  option,
BOOL  value 
)

Set boolean session option.

Sets the session option. This function was created to allow configuring the active session. There are only two options available currently:

  • CMP_SESSION_OPTION_IGNORE_FOREGROUND_CHECK
  • CMP_SESSION_OPTION_DISABLE_CACHE

CMP_SESSION_OPTION_IGNORE_FOREGROUND_CHECK controls whether or not the API enforces a foreground check. This option is FALSE by default. Some API should only be called while the application is in the foreground. Some API will reject certain calls if they are called in the background. Setting this option to TRUE will disable the foreground check and make it possible for the program to call any of the API regardless of the foreground/background status.

CMP_SESSION_OPTION_DISABLE_CACHE controls whether or not the mobile device values will be cached. Caching is on by default. In some cases it might be better to turn off caching. This means that requests to get values will go directly to the mobile device instead of using the cache.

Introduced: V1.0

Execution: Sync

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPGetSessionOptionBool

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
[in]optionsession option
[in]valueboolean session option value
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPSetSupportedOrientations ( HANDLE  hCMP,
CMP_SUPPORTED_ORIENTATIONS  supportedOrientations 
)

Set which orientations the application is going to support.

Once the application has set the supported orientations, the orientation position will only change to those supported

Execution: Sync

Introduced: V2.0

Context: Remote

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]supportedOrientationsorientations supported by the application
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/supportedorientations/supportedorientations.cpp.
CMPAPIENTRY CMPSetViewport ( HANDLE  hCMP,
INT16  flags,
INT16  zoomFactor,
CMP_DISPLAY_RECT serverViewport 
)

Set viewport.

Set the server viewport. This means what section of the server screen is currently visible on the device. Normally applications are sized to fit exactly on the device but there are times when the application is larger than the client device (based on settings and keyboard interaction).

The flags indicate which fields are valid.

CMP_VIEWPORT_VALID_FLAGS

  • CMP_VIEWPORT_VALID_FLAG_ZOOM_FACTOR = 0x0001 Zoom factor is valid
  • CMP_VIEWPORT_VALID_FLAG_SERVER_VIEWPORT = 0x0002 Server viewport is valid

The viewport specifies what content is to be shown. If the application is larger than the mobile device screen, it can use the viewport to switch to different sections of the application on the mobile device.

Setting the viewport also specifies the zoom factor. This could be used to zoom into a certain section with the specified viewport rectangular coordinates.

There is another set of API just to deal with the viewport origin. These API are the original functions. They are simpler but do not allow for the size of the viewport or the zoom factor. It is still okay to use the old API but the newer API is preferred.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_VIEWPORT

Foreground Required: No

Requires: CMPOpenSession

Related Function: CMPGetViewport CMPGetViewportOrigin CMPSetViewportOrigin

Related Event: ViewportChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]flagsindicates which of the parameters are valid (zoomFactor and/or serverViewPort) CMP_VIEWPORT_VALID_FLAGS
[in]zoomFactoramount to zoom the server viewport (100 = 1x, 200 = 2x)
[in]serverViewportrectangle the specifies the section of the server session to display
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPSetViewportOrigin ( HANDLE  hCMP,
CMP_DISPLAY_POINT pt,
UINT16  viewportFlags 
)

Set viewport origin.

Set the origin of the Citrix Receiver viewport

CMP_DISPLAY_POINT

  • Left x coordinate
  • Top y coordinate

The viewport origin is the top left corner of viewport into the server application. Typically it is (0,0) but change be changed by user action or CMPSetViewportOrigin.

The server application can use the viewport origin to select what part of the application is currently visible.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_VIEWPORT

Foreground Required: Yes

Requires: CMPOpenSession

Related Function: CMPGetViewportOrigin CMPGetViewport CMPSetViewport

Related Event: ViewportOriginChanged ViewportChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]ptLocation to position the viewport (top, left)
[in]viewportFlagsflags to control how set viewport works
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPShowKeyboard ( HANDLE  hCMP,
CMP_KEYBOARD_STATE kybdState 
)

Show the display keyboard.

Show the display keyboard with the given properties

CMP_KEYBOARD_TYPE selects the style of keyboard used. The keyboard types supported can be derived from the capabilities. Android only supports the standard ones while iOS has a larger variety. Probably the most obvious difference is between a standard keyboard and a numeric pad.

CMP_KEYBOARD_FLAGS reveal the current state of the keyboard.

  • CMP_KYBD_FLAG_PHYSICAL Physical keyboard available (readonly)
  • CMP_KYBD_FLAG_VISIBLE Display keyboard visible (readonly)
  • CMP_KYBD_FLAG_EXT_FLAG Extended kebyoard
  • CMP_KYBD_FLAG_USE_RECT Use rectangle co-ordinates for viewing section of display
  • CMP_KYBD_FLAG_AUTO_CORRECT Auto correct text
  • CMP_KYBD_FLAG_AUTO_CAPITAL Auto-capitalize text
  • CMP_KYBD_FLAG_RETURN_KEY_TYPE Return key text to show

The first two fields can only be retrieved. It is unlikely that the device has a physical keyboard attached but the CMP_KYBD_FLAG_PHYSICAL will be set if there is one there. If the on-screen keyboard is visible, the CMP_KYBD_FLAG_VISIBLE flag will be on. The on-screen keyboard can have extended keys like Tab, Esc, Del, Page Up, Page Down, Home, End, Cut, Copy, Paste, and Alt+Tab. These keys can be used to better control programs that expect these keys to be available. The CMP_KYBD_FLAG_EXT_FLAG indicates that these keys are present.

The remaining flags indicate the use of certain features.

  • Edit area location
  • Auto correct
  • Auto capitalization
  • Return key customization

If the bit is on for the USE_RECT, it means that the rectangle coordinates are valid and can be used for selecting which part of the server screen is visible. It is useful to have the text area on the screen as the user types the keys in. The program needs to gather and setthe rectangle coordinates before showing the keyboard and set the CMP_KYBD_FLAG_USE_RECT flag.

On iOS devices, it is possible to configure auto correction and capitalization. It also possible to specify a different return key label. These aspects are only enabled if the flags are set.

Capabilities reveal what is available. Check CMP_CAP_INPUT_KEY_ID for possible features.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_INPUT

Foreground Required: Yes

Requires: CMPOpenSession

Related Functions: CMPHideKeyboard CMPGetKeyboardState

Related Event: KeyboardStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]kybdStatekeyboard selection and other keyboard settings
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/showkeyboard/showkeyboard.cpp.
CMPAPIENTRY CMPShowPicker ( HANDLE  hCMP,
CMP_UNIQUE_ID  controlId,
CMP_DISPLAY_RECT rect,
UINT32  selectedIndex,
UINT32  listItemsSize,
UTF8_STRING  listItems,
UTF8_STRING  title 
)

Show picker control.

Show the picker control on the mobile device. The picker control is a list of strings that is displayed on the mobile device. Each string has its own row and is displayed in a similar way to a combo box on Windows. However, the picker control is displayed on the mobile device using native mobile device controls. The user selects one item and the control goes away.

The controlId is used to correspond the request with the the PickerControlStateChanged event.

selectedIndex is the pre-selected item in the list. This is the default selection.

listItemSize is the total size in bytes of the multiple string list.

listItems is a multistring in UTF-8 format. Each string is terminated with a zero, and to terminate the list the last string is zero length.

title is optional but is used for the title of the picker control on the mobile device.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_PICKER_CONTROL

Foreground Required: Yes

Requires: CMPOpenSession

Related Functions: CMPHidePicker CMPShowPickerUTF16 CMPGetPickerState

Related Event: PickerControlStateChanged

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]controlIdcontrol identifier
[in]rectviewport rectangle to use for text input area
[in]selectedIndexwhich item to have selected by default
[in]listItemsSizelength of multistring in bytes
[in]listItemspicker control text
[in]titlepicker control title
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/showpicker/showpicker.cpp.
CMPAPIENTRY CMPShowPickerUTF16 ( HANDLE  hCMP,
CMP_UNIQUE_ID  controlId,
CMP_DISPLAY_RECT rect,
UINT32  selectedIndex,
UINT32  listItemsSize,
LPCWSTR  listItems,
LPCWSTR  title 
)

Show picker control using wide characters.

Show the picker control on the mobile device. This uses standard Windows 16-bit Unicode.

Show the picker control on the mobile device. The picker control is a list of strings that is displayed on the mobile device. Each string has its own row and is displayed in a similar way to a combo box on Windows. However, the picker control is displayed on the mobile device using native mobile device controls. The user selects one item and the control goes away.

The controlId is used to correspond the request with the the PickerControlStateChanged event.

selectedIndex is the pre-selected item in the list. This is the default selection.

listItemSize is the total size in bytes of the multiple string list.

listItems is a multistring in UTF-16 format. Each string is terminated with a zero, and to terminate the list the last string is zero length.

title is optional but is used for the title of the picker control on the mobile device.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_PICKER_CONTROL

Foreground Required: Yes

Requires: CMPOpenSession

Related Functions: CMPHidePicker CMPShowPicker CMPGetPickerState

Related Event: PickerControlStateChanged

Includes: cmp.h

Libraries: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]controlIdcontrol identifier
[in]rectviewport rectangle to use for text input area
[in]selectedIndexwhich item to have selected by default
[in]listItemsSizelength of multistring in bytes
[in]listItemspicker control text
[in]titlepicker control title
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPStartCall ( HANDLE  hCMP,
UTF8_STRING  phoneNumber,
CMP_UNIQUE_ID  callId 
)

Start phone call.

Initiate a phone call using the mobile device. The phone call does not happen automatically to protect the user. In order for the phone call to happen, the user has to press the call button inside the dialer. The phone number is not limited to just numbers. In fact, the phone number can be anything that the mobile device can support.

When the mobile device processes the phone call request, it sends back an event to let the application know that the request arrived. The event can provide an error code if the phone had trouble starting the call.

The callId is used in the PhoneCallStarted event to identify the call request.

The phoneNumber is specified as a UTF-8 string so it may be necessary to use conversion routines if the phone number includes text and is using Windows Unicode (UTF-16).

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_PHONE_CALL

Foreground Required: Yes

Requires: CMPOpenSession

Related Event: PhoneCallStarted

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]phoneNumberphone number to dial
[in]callIdunique call identification
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/phonecall/phonecall.cpp.
CMPAPIENTRY CMPTakePicture ( HANDLE  hCMP,
CMP_UNIQUE_ID  pictureId,
CMP_IMAGE_FORMAT  imageFormat 
)

Start the process of taking a picture.

Take a picture with the specified image format and picture Id. If the device does not support a camera, then it will return that the device does not have that capability. This function requests the mobile device to take a picture but does not force the picture to be take immediately. Instead, the mobile device switches to the camera application so the user can decide when the picture is actually taken. A unique picture Id should be used to track the picture status and be able to retrieve the picture later.

It is very important to make sure the Android mobile receiver has allowed access to the SD card (read or full). Otherwise it is not possible to take pictures and download them. It is also important to allow CDM for the user's session.

Execution: Async

Introduced: V1.0

Context: Remote

Related Capability: CAPID_TAKE_PICTURE

Foreground Required: Yes

Requires: CMPOpenSession

Related Functions: CMPGetPictureFilename CMPGetPictureState CMPRemovePicture

Related Event: PictureTaken

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP Object
[in]pictureIdunique picture Id (specified by the caller)
[in]imageFormattype of picture format to take (JPEG or PNG)
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/takepicture/takepicture.cpp.
CMPAPIENTRY CMPUnregisterForEvent ( HANDLE  hCMP,
CMP_EVENT_ID  eventId,
CMP_EVENT_CALLBACK  eventHandler 
)

Unregister event handler.

Unregister event notification. Only allowed once for a given event.

CMP_EVENT_ID

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpenSession

Related Functions: CMPFilterEvent CMPUnregisterForEvent

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]eventIdevent identifier
[in]eventHandlerevent handler function
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY CMPUnregisterProcess ( HANDLE  hCMP,
DWORD  processId 
)

Unregister a process for CMP.

Since the child process can exit at any time, it is necessary to unregister the process on its behalf. Unregister is paired with Register otherwise the internal reference counts will be incorrect and the marker will incorrectly be there or not. Only the last unregister causes the marker to go away. The intent is to make it easier to have multiple callers deal with the same process in the same parent process.

When registration happens, the process should be the parent of the process being registered. Otherwise the register/unregister siutation could cause a problem across process boundaries.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Requires: CMPOpen

Related Functions: CMPProcessDetect CMPRegisterProcess

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[in]hCMPhandle to CMP object
[in]processIdprocess Id of the process to be unregistered
Returns:
CMPRESULT (CMP_ERROR_ID)
void CMPCALL ControlStateChanged ( HANDLE  hCMP,
CMPRESULT  rc,
UINT16  controlStateFlags 
)

Event: Control state changed.

Parameters:
hCMPhandle to CMP object
rcresult of last request
controlStateFlagsflags that indicate the state of the receiver controls
void CMPCALL DisplaySettingsChanged ( HANDLE  hCMP,
INT16  MetricFlags,
INT32  pixelWidth,
INT32  pixelHeight,
INT16  colorDepth,
INT32  XPixelsPerInch,
INT32  YPixelsPerInch,
CMP_ORIENTATION_POSITION  orientation,
INT32  WidthMilliInches,
INT32  HeightMilliInches,
INT32  normalizedDPI 
)

Event: Display settings have changed.

Parameters:
hCMPhandle to CMP object
MetricFlagsflags that indicate which of the following parameters is valid
pixelWidthwidth of display in pixels
pixelHeightheight of display in pixels
colorDepthcolor bits per pixel
XPixelsPerInchpixels per inch on horizontal axis
YPixelsPerInchpixels per inch on vertical axis
orientationdevice orientation
WidthMilliIncheswidth in milli-inches (1/1000 of an inch)
HeightMilliInchesheight in milli-inches (1/1000 of an inch)
normalizedDPIsome devices only report this approximate DPI value
Examples:
native/displaysettings/displaysettings.cpp, winform/displaysettings/CMPApp.cs, and winform/displaysettings/FormDisplaySettings.cs.
void CMPCALL FilterChanged ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_EVENT_ID  eventId,
INT16  filterFlags 
)

Event: Filter changed.

Parameters:
hCMPhandle to CMP object
rcresult of last request
eventIdevent identifier
filterFlagsflags for event filter (disable or enable)
void CMPCALL ForegroundAppChanged ( HANDLE  hCMP,
DWORD  foregroundProcessId 
)

Event: The foreground application has changed to another process.

Parameters:
hCMPhandle to CMP object
foregroundProcessIdThe PID of the process that is now in the foreground.

Get a unique Id for the upcoming request that needs one.

Since the unique Id only needs to be unique for just a few minutes, it is only 32-bits long.

Execution: Sync

Introduced: V2.0

Context: Local

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[out]uniqueIdreturned unique identifier
Returns:
CMPRESULT (CMP_ERROR_ID)

Get a long unique Id for the upcoming request that needs one.

Since the unique Id only needs to be unique for just a few minutes, it is only 64-bits long.

Execution: Sync

Introduced: V2.0

Context: Local

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
[out]uniqueIdreturned unique identifier
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY GetUTF16MultiStringLength ( LPCWSTR  str,
UINT32 *  length 
)

Get length of a UTF-16 multistring in characters.

Get length of a UTF-16 multistring. End of multistring is determined by two terminating '\0' characters. This function is very similar to GetUTF8MultiStringLength except it deals with UTF-16 strings.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions: UTF16ToUTF8Length UTF16ToUTF8MultiString UTF16ToUTF8

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
strUTF-16 multistring
lengthreturned length of multistring in characters
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY GetUTF16ToUTF8MultiStringLength ( LPCWSTR  str,
UINT32 *  length 
)

Get length of a UTF-16 multistring in UTF-8 format.

Get length of a standard UTF-16 multistring but expressed as a UTF-8 multistring. This function determines what the length of a UTF-16 would be if it was turned into a UTF-8 multistring. This is very useful for conversion.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions: UTF16ToUTF8Length UTF16ToUTF8MultiString UTF16ToUTF8

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
strUTF-16 multistring
lengthreturned length of multistring in characters
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY GetUTF8MultiStringLength ( UTF8_STRING  str,
UINT32 *  length 
)

Get length of a UTF-8 multistring in characters.

Get length of a standard UTF-8 multistring. End of multistring is determined by two terminating '\0'. This function could be useful for determining the length of a multistring before calling CMPShowPicker.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
strUTF-8 multistring
lengthreturned length of multistring in bytes
Returns:
CMPRESULT (CMP_ERROR_ID)
void CMPCALL KeyboardStateChanged ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_KEYBOARD_TYPE  keyboardType,
INT16  keyboardStateFlags,
CMP_KEYBOARD_AUTOCAPS  kybdAutoCap,
CMP_KEYBOARD_RETURNKEY  kybdReturnKey 
)

Event: Keyboard state changed.

Parameters:
hCMPhandle to CMP object
rcresult of last request
keyboardTypetype of keyboard that is displayed
keyboardStateFlagsflags associated with keyboard
kybdAutoCapauto capitalization mode selected
kybdReturnKeyreturn key text selected
Examples:
native/showkeyboard/showkeyboard.cpp.
void CMPCALL OrientationChanged ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_ORIENTATION_POSITION  deviceOrientation,
CMP_ORIENTATION_POSITION  appOrientation,
UINT16  orientationFlags 
)

Event: Orientation changed.

Parameters:
hCMPhandle to CMP object
rcresult of last request
deviceOrientationorientation position of the device
appOrientationorientation of the application
orientationFlagsEither sensor follow or lock
Examples:
native/orientation/orientation.cpp, winform/displaysettings/CMPApp.cs, and winform/displaysettings/FormOrientation.cs.
void CMPCALL PhoneCallStarted ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_UNIQUE_ID  phoneCallId 
)

Event: Phone call started.

Parameters:
hCMPhandle to CMP object
rcresult of last request
phoneCallIdunique phone call identifier for request
Examples:
native/phonecall/phonecall.cpp.
void CMPCALL PickerControlStateChanged ( HANDLE  hCMP,
CMP_UNIQUE_ID  pickerId,
INT16  pickerStateFlags,
CMPRESULT  rc,
INT16  selectedIndex 
)

Event: Picker control state changed.

Parameters:
hCMPhandle to CMP object
pickerIdunique identifier for picker control
pickerStateFlagsflags for picker control
rcresult of last request
selectedIndexselected list item
Examples:
native/showpicker/showpicker.cpp.
void CMPCALL PictureCaptured ( HANDLE  hCMP,
CMPRESULT  result,
CMP_UNIQUE_LONG_ID  uniqueId,
UTF8_STRING  pictureMetadata,
UTF8_STRING  filename,
UTF8_STRING  thumbnail,
INT32  pictureSize,
const CMP_CAPTURE_PICTURE_OPTIONS options 
)

Event: Picture captured.

Parameters:
hCMPhandle to CMP object
resultresult of the picture capture request. if error, then the other parameters are not valid
uniqueIdunique id of the picture request
pictureMetadatareturned picture metadata (including size and other interesting fields)
filenamelocation of the picture file
thumbnailThe location of the thumbail image file.
pictureSizeThe size of the picture in bytes.
optionsThe picture capture API uses fallback. So when the options you requested are not supported by the client device, it will automatically downgrade the request to use supported defaults. This options struct contains the option values that were used for the capture operation. You can compare them against your original request to determine if fallback was applied.
void CMPCALL PictureRemoved ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_UNIQUE_ID  pictureId 
)

Event: Picture removed.

Parameters:
hCMPhandle to CMP object
rcresult of last request
pictureIdunique picture identifier
void CMPCALL PictureTaken ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_UNIQUE_ID  pictureId,
CMP_IMAGE_FORMAT  pictureFormat,
UINT32  pictureSize,
UTF8_STRING  filename 
)

Event: Picture taken.

Parameters:
hCMPhandle to CMP object
rcresult of last request
pictureIdunique picture identifier
pictureFormattype of picture taken (JPEG, PNG)
pictureSizesize of the picture
filenamelocation of picture using filename
Examples:
native/takepicture/takepicture.cpp.
void CMPCALL ScrollModeChanged ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_SCROLL_MODE  scrollMode 
)

Event: Scroll mode changed.

Parameters:
hCMPhandle to CMP object
rcresult of last request
scrollModecurrent scroll mode
void CMPCALL SessionStateChanged ( HANDLE  hCMP,
CMP_SESSION_STATE  state 
)

Event: Session state changed.

Parameters:
hCMPhandle to CMP object
statelatest state for the session
Examples:
winform/displaysettings/CMPApp.cs.
void CMPCALL SMSStarted ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_UNIQUE_ID  SMSId 
)

Event: Send SMS Started.

Parameters:
hCMPhandle to CMP object
rcresult of last request
SMSIdunique SMS identifier for request
Examples:
native/sendsms/sendsms.cpp.
void CMPCALL SupportedOrientationsChanged ( HANDLE  hCMP,
CMPRESULT  result,
CMP_SUPPORTED_ORIENTATIONS  supportedOrientations 
)

Event: Supported orientations has changed.

Parameters:
hCMPhandle to CMP object
resultresult of the previous SetOrientationsSupported request
supportedOrientationsorientations supported by the application
Examples:
native/supportedorientations/supportedorientations.cpp.
void CMPCALL UserNotified ( HANDLE  hCMP,
CMPRESULT  rc,
CMP_UNIQUE_ID  notificationId 
)

Event: User notified.

Parameters:
hCMPhandle to CMP object
rcresult of last request
notificationIdunique notification identifier
Examples:
native/notifyuser/notifyuser.cpp.
CMPAPIENTRY UTF16ToUTF8 ( LPCWSTR  wStr,
INT32  wStrLen,
UTF8_STRING  utf8String,
UINT32  utf8Size,
UINT32 *  utf8Length 
)

Convert from UTF-16 text to UTF-8.

Take a typical Windows wide string and make it into UTF-8 format. utf8String is a buffer that the caller has allocated. wStrLen is the character count with wStr being a Windows Unicode string (2 bytes per character).

utf8Size should be big enough to hold the resulting string. Use UTF16ToUTF8Length to determine what the length should be ahead of time.

The most likely use of this API is to convert Windows Unicode into UTF-8 for the sake of calling CMP API functions.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions: UTF16ToUTF8Length UTF16ToUTF8MultiString GetUTF16ToUTF8MultiStringLength

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
wStrwide string to convert
wStrLenlength of string in characters (-1 for zero terminated string)
utf8Stringresulting string conversion in caller supplied buffer
utf8Sizesize of UTF-8 buffer
utf8Lengthlength of returned UTF-8 string in characters
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY UTF16ToUTF8Length ( LPCWSTR  wstring,
UINT32 *  length 
)

Calculate the length of a UTF-16 string as if it is really UTF-8.

Conversion of strings from UTF-16 to UTF-8 implies that a dynamic buffer is allocated by the caller. Unfortunately, it is hard to know the size of the required buffer. This function determines the true size of the resulting conversion string before it is converted.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
wstringUTF-16 string
lengthreturned UTF-8 size
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY UTF16ToUTF8MultiString ( LPCWSTR  wStr,
UTF8_STRING  utf8string,
UINT32  stringBufSize,
UINT32 *  stringSize 
)

Convert a UTF-16 multistring into a UTF-8 multistring.

Converting a multistring can be tricky since there are multiple strings to deal with. This function automatically converts the UTF-16 multistring to UTF-8 multistring. The GetUTF16ToUTF8MultiStringLength function can be used to determine the exact stringBufSize ahead of time. stringSize returns the actual size of the UTF-8 multistring in bytes.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
wStrUTF-16 multistring
utf8stringresulting UTF-8 multistring
stringBufSizesize of buffer for converted UTF-8 multistring
stringSizereturned UTF-8 multistring size
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY UTF8MultiStringToBSTR ( UTF8_STRING  str,
BSTR *  bStr 
)

Convert a UTF-8 multistring into a single BSTR.

BSTR can contain '\0' since it is specified by a length instead of '\0' termination. This means that a multistring can be contained in a single BSTR. The BSTR is allocated during this function call and must be freed later with SysFreeString.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
strUTF-8 multistring
bStrconverted string in BSTR format. BSTR uses UTF-16 encoding.
Returns:
CMPRESULT (CMP_ERROR_ID)
CMPAPIENTRY UTF8ToBSTR ( UTF8_STRING  utf8string,
INT32  length,
BSTR *  bStr 
)

Convert from UTF-8 text to BSTR.

Take a UTF-8 string and convert it into a BSTR (commonly used with COM automation). This function does not need a preallocated buffer. However, it is important to free the bStr with SysFreeString when it is no longer needed. UTF-16 and BSTR are very similar but the BSTR has a specified length before the string and is not necessarily null terminated.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
utf8stringwide string to convert
lengthlength of string in characters (-1 for zero terminated string)
bStrresulting string conversion in API supplied memory. Need to free BSTR later with SysFreeString.
Returns:
CMPRESULT (CMP_ERROR_ID)
Examples:
native/takepicture/takepicture.cpp.
CMPAPIENTRY UTF8ToUTF16Length ( UTF8_STRING  utf8string,
UINT32 *  length 
)

Calculate the length of a UTF-8 string as if it is really UTF-16.

Conversion of strings from UTF-8 to UTF-16 implies that a dynamic buffer is allocated by the caller. Unfortunately, it is hard to know the size of the required buffer. This function determines the true size of the resulting conversion string before it is converted.

Execution: Sync

Introduced: V1.0

Context: Local

Foreground Required: No

Related Functions:

Include: cmp.h

Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)

Parameters:
utf8stringUTF-8 string
lengthreturned UTF-16 size
Returns:
CMPRESULT (CMP_ERROR_ID)
void CMPCALL VideoCaptured ( HANDLE  hCMP,
CMPRESULT  result,
CMP_UNIQUE_LONG_ID  uniqueId,
UTF8_STRING  videoMetadata,
UTF8_STRING  filename,
INT32  videoSize,
const CMP_CAPTURE_VIDEO_OPTIONS options 
)

Event: Video captured.

Parameters:
hCMPhandle to CMP object
resultresult of the video capture request. if error, then the other parameters are not valid
uniqueIdunique id of the video request
videoMetadatareturned video metadata (including size and other interesting fields)
filenamelocation of the video file
videoSizeThe size of the video file in bytes.
optionsThe video capture API uses fallback. So when the options you requested are not supported by the client device, it will automatically downgrade the request to use supported defaults. This options struct contains the option values that were used for the capture operation. You can compare them against your original request to determine if fallback was applied.
Examples:
native/capturevideo/capturevideo.cpp.
void CMPCALL ViewportChanged ( HANDLE  hCMP,
CMPRESULT  rc,
INT16  flags,
INT16  zoomFactor,
INT32  x0Server,
INT32  y0Server,
INT32  x1Server,
INT32  y1Server,
INT32  x0Client,
INT32  y0Client,
INT32  x1Client,
INT32  y1Client 
)

Event: Viewport changed.

Parameters:
hCMPhandle to CMP object
rcresult of last request
flagsindicates which fields are valid
zoomFactoramount of zoom to applied to server viewport
x0Serverserver viewport left x coordinate
y0Serverserver viewport top y coordinate
x1Serverserver viewport right x coordinate
y1Serverserver viewport bottom y coordinate
x0Clientclient viewport left x coordinate
y0Clientclient viewport top y coordinate
x1Clientclient viewport right x coordinate
y1Clientclient viewport bottom y coordinate
void CMPCALL ViewportOriginChanged ( HANDLE  hCMP,
CMPRESULT  rc,
INT32  left,
INT32  top 
)

Event: Viewport origin changed.

Parameters:
hCMPhandle to CMP object
rcresult of last request
leftleft most position
toptop most position
typedef void ( CMPCALL PFN_EVENT_BUTTON_PRESSED)
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Events Defines