 |
XenApp 6.5 Mobile Application SDK 1.0
XAMA API
|
|
XenApp 6.5 Mobile Application SDK 1.0
XAMA API
|
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 "Trace.h"#include "cmpapi.tmh"#include "cmpevthdlr.h"#include "cmpwrapper.h"Functions | |
| CMPAPIENTRY | CMPOpen (HANDLE *phCMP) |
| Open CMP handle. | |
| CMPAPIENTRY | CMPClose (HANDLE hCMP) |
| Close CMP handle. | |
| CMPAPIENTRY | CMPGetAPIVersion (HANDLE hCMP, CMP_VERSION *cmpVersion) |
| Get 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 XAMP. | |
| CMPAPIENTRY | CMPRegisterProcess (HANDLE hCMP, DWORD processId) |
| Register a process for XAMP. | |
| 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. | |
| 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 event. | |
| 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 XAMA. | |
| CMPAPIENTRY | CMPUninitialize () |
| Uninitialize COM for XAMA. | |
| 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
Copyright (c) 2011 - Citrix Systems, Inc.
| 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
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 CMP handle.
Close the CMP handle and free any associated resources. Events handlers will no longer be notified once the handle is closed.
Execution: Sync
Introduced: V1.0
Context: Local
Requires: CMPOpen
Related function: CMPOpen
Include: cmp.h
Library: cmpapi.lib (32-bit) or cmpapi64.lib (64-bit)
| hCMP | handle to CMP Object |
this will destroy the CMP and event handler objects also
| CMPAPIENTRY CMPCloseSession | ( | HANDLE | hCMP | ) |
Close session connection.
Closes the current session connection with the client. Each application can have its own connection to the client and closing the session connection will not have an effect on the other session connections.
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
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.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_RECEIVER_CONTROLS
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.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_RECEIVER_CONTROLS
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 event.
Filter specific events
Execution: Sync
Introduced: V1.0
Context: Local
Related Capability: CAPID_EVENT_FILTER
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 API Version.
The XAMA 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 XA 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 XAMA API. The second part of 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
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 client. The host application will be notified of button events if it is the destination. Otherwise the client (mobile device) will handle it like normal.
Execution: Sync
Introduced: V1.0
Context: Remote
Result Data Cached: Yes
Related Capability: CAPID_BUTTON_SET_TARGET
Requires: CMPOpenSession
Related Function: CMPSetButtonTarget
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 | 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.
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
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.
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
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.
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
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.
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
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.
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
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 what the current channel state is. This is useful to determine if channel is active. This value only reflects the state of the current process virtual channel and not the global MRVC 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 few states before it can talk to the other side (client).
Execution: Sync
Introduced: V1.0
Context: Local
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.
Execution: Sync
Introduced: V1.0
Context: Remote
Result Data Cached: Yes
Related Capability: CAPID_RECEIVER_CONTROLS
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
Execution: Sync
Introduced: V1.0
Context: Remote
Result Data Cached: Yes
Related Capability: CAPID_DEVICE_INFO
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 on the device and also an easy way to publish flexible information.
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
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
Execution: Sync
Introduced: V1.0
Context: Remote
Result Data Cached: Yes
Related Capability: CAPID_DISPLAY_INFO
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.
In a given server or development machine, it can be difficult to determine which DLL is being used. 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 XAMP 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 location is determined by the COM registration in the registry.
Execution: Sync
Introduced: V1.0
Context: Local
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
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 and application orientation can be different based on the orientation flags.
Execution: Sync
Introduced: V1.0
Context: Remote
Result Data Cached: Yes
Related Capability: CAPID_ORIENTATION
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
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.
Execution: Sync
Introduced: V1.0
Context: Remote
Result Data Cached: Yes
Related Capability: CAPID_TAKE_PICTURE
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
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. For everything we can set, the intention is being able to retrieve those settings as well.
Execution: Sync
Introduced: V1.0
Context: Remote
Result Data Cached: Yes
Related Capability: CAPID_SCROLL_MODES
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 session option. Session options can apply immediately to the session depending on the option chosen. This function was introduced to control an option to ignore being in the foreground for certain API and events. It can also be used to control returned data being cached. Other options will be added over time.
Execution: Sync
Introduced: V1.0
Context: Local
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.
Execution: Sync
Introduced: V1.0
Context: Local
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.
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
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
Execution: Sync
Introduced: V1.0
Context: Remote
Result Data Cached: Yes
Related Capability: CAPID_VIEWPORT
Requires: CMPOpenSession
Related Function: CMPSetViewportOrigin
Related Event: ViewportOriginChanged
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.
Execution: Async
Introduced: V1.0
Related Capability: CAPID_INPUT
Context: Remote
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 of heart 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
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 XAMA.
Need to have COM initialized in order for CMPAPI to work
Execution: Sync
Introduced: V1.0
Context: Local
Related Function: CMPUninitialize
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.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_NOTIFICATION
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 | ) |
Open CMP handle.
Create the CMP object and return a CMP handle. It is required that COM is initialized first. Either use CMPInitialize or CoInitialize. If not already using COM, CMPInitialize is preferred. Handle is used for all future CMP-related calls. Only need to initialize COM once per thread. 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 mobile device will only happen once CMPOpenSession is called successfully. Once the program wants to exit or just terminate the connection, it should call CMPClose.
Execution: Sync
Context: Local
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 the session connection with the client. Each application can have its own connection to the client and opening the session connection will not have an effect on the other session connections. The connection is needed before any other exchange happens between the server and client.
It is not widely know that it is not required to call CMPOpenSession before using functions that require a connection. Each function that requires an active session automatically calls the equivalent of CMPOpenSession so that it will be in the correct state before the call runs.
Internally this function starts communication with a service which in turn connects to the client (Mobile Receiver). At the time of this writing, only Android and iOS (Apple) are supported. The mobile device needs a minimum level of support that includes the MRVC virtual channel support.
The most common failure for this function is when the client is not a version that supports 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
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 XAMP.
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 XAMA SDK API.
In general it is not necessary to know about this feature. The reason why is that the XAMP 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 XAMP directly.
To explain this from a completely different angle, registering with XAMP is important to stop any kind of automatic processing. For example, the XAMP 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 XAMP do not need this. They can manage on their own and do want any kind of outside assistance. Even programs that are not using XAMP 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
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.
Execution: Sync
Introduced: V1.0
Context: Local
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 XAMP.
It is sometimes necessary to mark a child process as using XAMP even though it might not be using it directly. This creates a marker that lives until the process is unregistered with CMPUnregisterProcess.
The registration of the process lives 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. 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 dies early or unexpectantly, the parent will have to catch that 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 XAMP process. This would block the automatic mobile device features for that process.
Execution: Sync
Introduced: V1.0
Context: Local
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. We no longer need it for download and there is no reason to keep it on the device. This function only works with images that were taken with our API. The pictureId only works with our pictures. The client does not know if it is okay to delete a picture until it is told.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_TAKE_PICTURE
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
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_SMS
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 client. The host application will be notified of button events if it is the target. Otherwise the client (mobile device) will handle it.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_BUTTON_SET_TARGET
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.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_ORIENTATION
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.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_SCROLL_MODES
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. Session options can apply immediately to the session depending on the option chosen. This function was introduced to control an option to ignore being in the foreground for certain API and events. It also controls whether or not the returned data is cached. Other options will be added over time.
Introduced: V1.0
Execution: Sync
Context: Local
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 | returned 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 viewport specifies what content is to be shown. If the application is fully aware of the visual elements, it can use the viewport to switch to different sections of the application or just to certain elements 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
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
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_VIEWPORT
Requires: CMPOpenSession
Related Function: CMPGetViewportOrigin
Related Event: ViewportOriginChanged
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
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_INPUT
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.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_PICKER_CONTROL
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.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_PICKER_CONTROL
Requires: CMPOpenSession
Related Functions: CMPHidePicker CMPShowPicker 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 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 device processes the phone call request, it sends back an event to let the application that it arrived. The event can return an error if the phone had trouble starting the call.
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_PHONE_CALL
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. It is not yet possible to retrieve the picture with the CMP API. This function does not actually signal when the photo should be taken. Instead, it switches to the camera application so the user can signal when the picture is actually taken. A unique picture Id should be used to track the picture status and be able to retrieve the data
Execution: Async
Introduced: V1.0
Context: Remote
Related Capability: CAPID_TAKE_PICTURE
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) |
| CMPAPIENTRY CMPUninitialize | ( | ) |
Uninitialize COM for XAMA.
Need to release COM initialization
Execution: Sync
Introduced: V1.0
Context: Local
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.
Execution: Sync
Introduced: V1.0
Context: Local
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 processId for its benefit. 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 parent should really be the parent for the process being created. Otherwise the register/unregister siutation could cause a problem across process boundaries.
Execution: Sync
Introduced: V1.0
Context: Local
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.
Execution: Sync
Introduced: V1.0
Context: Local
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.
Execution: Sync
Introduced: V1.0
Context: Local
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'.
Execution: Sync
Introduced: V1.0
Context: Local
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 characters |
| 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
Execution: Sync
Introduced: V1.0
Context: Local
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
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.
Execution: Sync
Introduced: V1.0
Context: Local
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
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)
Execution: Sync
Introduced: V1.0
Context: Local
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
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.3