 |
Mobile SDK for Windows Apps 1.0
Extending Windows Apps for Mobile
|
|
Mobile SDK for Windows Apps 1.0
Extending Windows Apps for Mobile
|
CMPAPI - C interface calls for CMP Object. More...
#include <windows.h>#include <cmp.h>#include <cmpstr.h>#include <cmpobject.h>#include <stdio.h>#include <strsafe.h>#include <new>#include "Trace.h"#include "cmpapi.tmh"#include "cmpevthdlr.h"#include "cmpwrapper.h"Functions | |
| 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 | CMPGetChannelState (HANDLE hCMP, CMP_CHANNEL_STATE *state) |
| Get the current channel 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, PBOOL value) |
| Get device boolean property. | |
| CMPAPIENTRY | CMPGetDevicePropertyString (HANDLE hCMP, CMP_DEV_STRING_PROP_ID propertyId, UTF8_STRING propertyString, UINT32 propertyStringLen, 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 listItemsSize, UTF8_STRING listItems, UTF8_STRING title) |
| Show picker control. | |
| 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. | |
| 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 | CMPFilterEvent (HANDLE hCMP, CMP_EVENT_ID eventId, UINT16 filterFlags) |
| Filter specific events. | |
| 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. | |
| 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 | CMPInitialize (BOOL MultiThreadedApartment) |
| Initialize COM for CMP. | |
| CMPAPIENTRY | CMPUninitialize () |
| Uninitialize COM for CMP. | |
| CMPAPIENTRY | UTF16ToUTF8 (LPCWSTR wStr, INT32 wStrLen, UTF8_STRING utf8String, UINT32 utf8Size, UINT32 *utf8Length) |
| Convert from UTF-16 text to UTF-8. | |
| CMPAPIENTRY | UTF8ToBSTR (UTF8_STRING utf8string, 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 str, BSTR *bStr) |
| Convert a UTF-8 multistring into a single BSTR. | |
| CMPAPIENTRY | UTF16ToUTF8MultiString (LPCWSTR wStr, UTF8_STRING utf8string, UINT32 stringBufSize, UINT32 *stringSize) |
| Convert a UTF-16 multistring into a UTF-8 multistring. | |
| 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 | BSTRSafearrayToBSTR (SAFEARRAY *psa, BSTR *bstr) |
| Convert a BSTR Safearray to a single BSTR for use with multiple string support. | |
CMPAPI - C interface calls for CMP Object.
Main file for CMPAPI(64).DLL which defines the CMP entry points
| 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)
| psa | pointer to BSTR safearray |
| bstr | returned single BSTR (multiple BSTRs combined) |
| 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)
| hCMP | handle to CMP Object |
| 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)
| hCMP | handle to CMP Object |
| 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)
| hCMP | handle to CMP object |
| 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)
| hCMP | handle to CMP object |
| 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)
| hCMP | handle to CMP object |
| eventId | event identifier |
| filterFlags | turn on/off event using flags CMP_FILTER_EVENT_DISABLE and CMP_FILTER_EVENT_ENABLE |
| 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)
| hCMP | handle to CMP object |
| cmpVersion | returns the requested versions from CMP |
| 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)
| hCMP | handle to CMP Object |
| buttonId | button identification (home, search, back, etc.) |
| buttonTarget | pointer to destination for button events (server or client) |
| 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)
| hCMP | handle to CMP object |
| capId | capability category identification |
| keyId | capability key identification |
| value | returned boolean value |
| 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)
| hCMP | handle to CMP object |
| capId | capability category identification |
| keyId | capability key identification |
| value | returned value |
| 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)
| hCMP | handle to CMP object |
| capId | capability category identification |
| keyId | capability key identification |
| value | returned value |
| 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)
| hCMP | handle to CMP object |
| capId | capability category identification |
| keyId | capability key identification |
| value | returned value |
| 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)
| hCMP | handle to CMP object |
| capId | capability category identification |
| keyId | capability key identification |
| value | returned value |
| 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).
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)
| hCMP | handle to CMP Object |
| state | state (connected, disconnected, bound, etc...) |
| 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)
| hCMP | handle to CMP object |
| controlFlags | returned flags for controls |
| CMPAPIENTRY CMPGetDevicePropertyBool | ( | HANDLE | hCMP, |
| CMP_DEV_BOOL_PROP_ID | propertyId, | ||
| PBOOL | value | ||
| ) |
Get device boolean property.
Get 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 connection.
Examples:
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)
| hCMP | handle to CMP object |
| propertyId | device property id |
| value | returned boolean value |
| 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)
| hCMP | handle to CMP object |
| propertyId | unique property Id to get |
| propertyString | buffer used to return string |
| propertyStringLen | buffer size |
| returnedSize | returned size in bytes |
| CMPAPIENTRY CMPGetDisplaySettings | ( | HANDLE | hCMP, |
| CMP_DISPLAY_SETTINGS * | dispSettings | ||
| ) |
Get display settings.
Get the current display settings for the mobile device
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)
| hCMP | handle to CMP object |
| dispSettings | display settings |
| 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:
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)
| hCMP | handle to CMP object |
| DLLfilename | name of the CMP DLL to get the path for |
| DLLfilepath | resulting DLL path |
| pathLength | length of the path buffer |
| 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.
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.
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)
| hCMP | handle to CMP object |
| kybdState | keyboard selection and other keyboard settings |
| 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_FLAG values
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)
| hCMP | handle to CMP object |
| orientationData | contains the relevant orientation data |
| 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.
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)
| hCMP | handle to CMP object |
| controlId | picker control identifier |
| pickerState | returned picker state CMP_PICKER_CONTROL_STATE |
| 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)
| hCMP | handle to CMP object |
| pictureId | unique picture identifier |
| filename | returned filename for picture |
| bufferLength | length of the filename buffer |
| returnedLength | length of filename returned |
| 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)
| hCMP | handle to CMP object |
| pictureId | unique picture identifier |
| size | returned size of picture |
| pictState | returned state of the picture (downloading, downloaded) |
| CMPAPIENTRY CMPGetScrollMode | ( | HANDLE | hCMP, |
| CMP_SCROLL_MODE * | scrollMode | ||
| ) |
Get scroll mode.
Get the current scroll mode from the mobile device.
Scroll modes:
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.
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)
| hCMP | handle to CMP object |
| scrollMode | returned scroll mode |
| 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 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)
| hCMP | handle to CMP Object |
| option | session option |
| value | returned boolean session option value |
| 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.
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)
| hCMP | handle to CMP Object |
| sessionState | session state (connected, disconnected, locked, unlocked, etc...) |
| 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
There is a reason why there are two viewports.
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)
| hCMP | handle to CMP object |
| flags | indicate which fields have been returned CMP_VIEWPORT_VALID_FLAGS |
| zoomFactor | amount of zoom being used (100 = 1x, 200 = 2x) |
| serverViewport | rectangle that specifies coordinates of server viewport in server coordinate framework |
| clientViewport | rectangle that specifies coordinates of client viewport in client coordinate framework |
| CMPAPIENTRY CMPGetViewportOrigin | ( | HANDLE | hCMP, |
| CMP_DISPLAY_POINT * | pt | ||
| ) |
Get viewport origin.
Get the origin of the Citrix Receiver viewport.
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)
| hCMP | handle to CMP object |
| pt | Location of the position of the viewport (top, left) |
| 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)
| hCMP | handle to CMP object |
| 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)
| hCMP | handle to CMP object |
| controlId | picker control identifier |
| 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)
| MultiThreadedApartment |
| 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
Notification types
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)
| hCMP | handle to CMP object |
| notificationId | notification identifier |
| notificationFlags | controls which options are used |
| notificationText | text to display (if notification flag for text is set) |
| 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)
| phCMP | pointer to CMP Object handle (returned on successful completion) |
| 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: Citrix Android Receiver 3.0 (late 2011) Citrix iOS Receiver 5.5 (early 2012)
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)
| hCMP | handle to CMP Object |
| 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 why 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)
| hCMP | handle to CMP object |
| processId | process Id of the process to be checked |
| detectFlag | indicates if it is using CMP (TRUE) or it is a legacy application (FALSE) |
| 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
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)
| hCMP | handle to CMP object |
| eventId | event identifier |
| eventHandler | event handler function |
| 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)
| hCMP | handle to CMP object |
| processId | process Id of the process to be registered |
| 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)
| hCMP | handle to CMP object |
| pictureId | unique picture identifier |
| 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)
| hCMP | handle to CMP object |
| phoneNumber | phone number for destination |
| msgId | message identifier |
| SMSText | text to send with the SMS |
| 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)
| hCMP | handle to CMP Object |
| buttonId | button identification (home, search, back, etc.) |
| buttonTarget | destination for button events (server or client) |
| 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_FLAG values
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)
| hCMP | handle to CMP object |
| orientation | contains the relevant orientation data |
| orientationFlags | controls the orientation to either be "follow" or "locked" |
| CMPAPIENTRY CMPSetScrollMode | ( | HANDLE | hCMP, |
| CMP_SCROLL_MODE | scrollMode | ||
| ) |
Set scroll mode.
Set the scroll mode for the mobile device.
Scroll modes:
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.
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)
| hCMP | handle to CMP object |
| scrollMode | scroll mode |
| 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 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)
| hCMP | handle to CMP Object |
| option | session option |
| value | boolean session option value |
| 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
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)
| hCMP | handle to CMP object |
| flags | indicates which of the parameters are valid (zoomFactor and/or serverViewPort) CMP_VIEWPORT_VALID_FLAGS |
| zoomFactor | amount to zoom the server viewport (100 = 1x, 200 = 2x) |
| serverViewport | rectangle the specifies the section of the server session to display |
| CMPAPIENTRY CMPSetViewportOrigin | ( | HANDLE | hCMP, |
| CMP_DISPLAY_POINT * | pt, | ||
| UINT16 | viewportFlags | ||
| ) |
Set viewport origin.
Set the origin of the Citrix Receiver viewport
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)
| hCMP | handle to CMP object |
| pt | Location to position the viewport (top, left) |
| viewportFlags | flags to control how set viewport works |
| 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.
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.
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)
| hCMP | handle to CMP object |
| kybdState | keyboard selection and other keyboard settings |
| 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)
| hCMP | handle to CMP object |
| controlId | control identifier |
| rect | viewport rectangle to use for text input area |
| selectedIndex | which item to have selected by default |
| listItemsSize | length of multistring in bytes |
| listItems | picker control text |
| title | picker control title |
| 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)
| [in] | hCMP | handle to CMP object |
| [in] | controlId | control identifier |
| [in] | rect | viewport rectangle to use for text input area |
| [in] | selectedIndex | which item to have selected by default |
| [in] | listItemsSize | length of multistring in bytes |
| [in] | listItems | picker control text |
| [in] | title | picker control title |
| 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)
| hCMP | handle to CMP object |
| phoneNumber | phone number to dial |
| callId | unique call identification |
| 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)
| hCMP | handle to CMP Object |
| pictureId | unique picture Id (specified by the caller) |
| imageFormat | type of picture format to take (JPEG or PNG) |
Uninitialize COM for CMP.
Need to release COM initialization
Execution: Sync
Introduced: V1.0
Context: Local
Foreground Required: No
Related Function: CMPInitialize
Include: cmp.h
Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)
| 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)
| hCMP | handle to CMP object |
| eventId | event identifier |
| eventHandler | event handler function |
| 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)
| hCMP | handle to CMP object |
| processId | process Id of the process to be unregistered |
| 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)
| str | UTF-16 multistring |
| length | returned length of multistring in characters |
| 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)
| str | UTF-16 multistring |
| length | returned length of multistring in characters |
| 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)
| str | UTF-8 multistring |
| length | returned length of multistring in bytes |
| 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)
| wStr | wide string to convert |
| wStrLen | length of string in characters (-1 for zero terminated string) |
| utf8String | resulting string conversion in caller supplied buffer |
| utf8Size | size of UTF-8 buffer |
| utf8Length | length of returned UTF-8 string in characters |
| 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)
| wstring | UTF-16 string |
| length | returned UTF-8 size |
| 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)
| wStr | UTF-16 multistring |
| utf8string | resulting UTF-8 multistring |
| stringBufSize | size of buffer for converted UTF-8 multistring |
| stringSize | returned UTF-8 multistring size |
| 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)
| str | UTF-8 multistring |
| bStr | converted string in BSTR format. BSTR uses UTF-16 encoding. |
| 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)
| utf8string | wide string to convert |
| length | length of string in characters (-1 for zero terminated string) |
| bStr | resulting string conversion in API supplied memory. Need to free BSTR later with SysFreeString. |
| 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)
| utf8string | UTF-8 string |
| length | returned UTF-16 size |
1.7.6.1