The MCOP integration API is provided by the UE vendor to abstract away differences between platforms and allows the SDK access to the lower levels of the system, mostly modem and SIM.

1.2. Architecture

1.2.1. On platform independence

To allow for easy implementation on many languages and platforms the design is kept intentionally simple. Parameter types are chosen to be primitives wherever possible to enable easier implementation.

In addition certain aspects of the API are defined “platform defined” – these parts must be implemented using the underlying HW or OS to provide certain functionality to the integration API.

1.2.2. Separate services

The API is split between different services. This version of the API defines four services: Connectivity, SIM, eMBMS and Configuration.

While the services are separate and each defines its own sub-APIs, all follow a common template for basic things that are shared between services, such as error handling and notifications.

1.2.3. Platform specific parts

Some parts of the defined API are marked as “platform specific”. The functionality of these functions or classes needs to be defined separately for each target platform. Currently only one such part exists:

Notifications / McopMessenger class; this class implements a way for the services to send back messages or callbacks to the SDK.

1.2.4. Android implementation

Service APIs will be defined in AIDL (Android Interface Definition Language). This is in essence a Java interface block, with some additional Android specific syntax. AIDL auto-generates a Binder interface to simulate a synchronous function call from the caller’s perspective.

The notification system will be internally implemented with android’s Messenger class, allowing the services to send notifications to the SDK process. The McopMessenger class is included in section 8.6.

In Android, the integration API services are exposed in the org.mcopenplatform.iapi namespace. Each service defines the package name and action needed to bind to it.

Service	Bind target	See also
Connectivity	org.mcopenplatform.iapi.ConnectivityService	8.1
SIM	org.mcopenplatform.iapi.SimService	8.3
eMBMS
Configuration	org.mcopenplatform.iapi.ConfigurationService	8.4

Constants used by the API are defined in the Constants class, see section 8.5.

1.2.5. Future implementations on other operating systems

As an example, a C implementation would likely be best done using a DLL that exposes an API similar to the Android AIDL one, hiding the OS specific messaging required. Given a part of the Android version of the API

interface IMcopConnectivityService {
    String getErrorStr();
    int getErrorCode();
    boolean createAPN(String name, String type);
}

This can be converted to a C API almost directly

char *getErrorStr(void);
int getErrorCode(void);
int createAPN(const char *name, const char *type);

The conversion to C can be done easily. Care just needs to be taken to specify the lifetimes and ownership of dynamically allocated memory.

1.3. Data formats

To keep things simple and ease future porting to different platforms or languages, the API only utilizes primitive types and arrays whenever possible, with a minimal number of platform-specific definitions.

1.4. Interfaces

1.4.1. Get error code operation

1.4.1.i. Definition

Message	Requirement	Direction
getErrorCodeRequest	Mandatory	SDK ➔ IAPI
getErrorCodeResponse	Mandatory	IAPI ➔ SDK

Table 78: Get error code operation

1.4.1.ii. Input parameters

None

1.4.1.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
errorCode	M	1	Integer	An integer describing the last error

Table 79: Get error code parameters

1.4.2. Get error string operation

1.4.2.i. Definition

Message	Requirement	Direction
getErrorStringRequest	Mandatory	SDK ➔ IAPI
getErrorStringResponse	Mandatory	IAPI ➔ SDK

Table 80: Get error string operation

1.4.2.ii. Input parameters

None

1.4.2.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
errorString	M	1	String	A string describing the last error. Useful for debugging, but note that this string may not be localized for the user.

Table 81: Get error string parameters

1.4.3. Register notification receiver operation

1.4.3.i. Definition

Message	Requirement	Direction
registerNotificationReceiverRequest	Mandatory	SDK ➔ IAPI
registerNotificationReceiverResponse	Mandatory	IAPI ➔ SDK

Table 82: Register notification receiver operation

1.4.3.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
receiver	M	1	McopMessenger	Messenger to receive the notifications

Table 83: Register notification receiver parameters

1.4.3.iii. Output parameters

None

1.4.4. Check capability operation

1.4.4.i. Definition

Message	Requirement	Direction
checkCapabilityRequest	Mandatory	SDK ➔ IAPI
checkCapabilityResponse	Mandatory	IAPI ➔ SDK

Table 84: Check capability operation

1.4.4.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
cap	M	1	Integer	Capability to check

Table 85: Check capability parameters

1.4.4.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	M	1	Integer	Capability value, or -1 if the capability is invalid; for boolean capabilities 0 for unsupported, 1 for supported

Table 86: Check capability parameters

1.4.5. Check capability list operation

1.4.5.i. Definition

Message	Requirement	Direction
checkCapabilityListRequest	Mandatory	SDK ➔ IAPI
checkCapabilityListResponse	Mandatory	IAPI ➔ SDK

Table 87: Check capability operation

1.4.5.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
cap	M	1	Integer	Capability to check

Table 88: Check capability parameters

1.4.5.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	O	0..N	String	List describing the requested capability, empty (zero element) list if unsupported, or nothing if the capability is invalid

Table 89: Check capability parameters

1.4.6. APN creation operation

1.4.6.i. Definition

Message	Requirement	Direction
createAPNRequest	Mandatory	SDK ➔ IAPI
createAPNResponse	Mandatory	IAPI ➔ SDK

Table 90: APN creation operation

1.4.6.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
name	M	1	String	Name of the new APN

Table 91: APN creation input parameters

1.4.6.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	M	1	Boolean	true if APN was created was successfully, false otherwise

Table 92: APN creation output parameters

1.4.7. APN activation operation

1.4.7.i. Definition

Message	Requirement	Direction
activateAPNRequest	Mandatory	SDK ➔ IAPI
activateAPNResponse	Mandatory	IAPI ➔ SDK

Table 93: APN activation operation

1.4.7.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
name	M	1	String	Name of the APN to activate

Table 94: APN activation input parameters

1.4.7.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	M	1	Boolean	true if APN was successfully activated, false otherwise

Table 95 APN activation output parameters

1.4.8. APN deletion operation

1.4.8.i. Definition

Message	Requirement	Direction
deleteAPNRequest	Mandatory	SDK ➔ IAPI
deleteAPNResponse	Mandatory	IAPI ➔ SDK

Table 96: APN deletion operation

1.4.8.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
name	M	1	String	Name of the APN to delete

Table 97: APN deletion input parameters

1.4.8.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	M	1	Boolean	true if APN was successfully deleted, false otherwise

Table 98: APN deletion output parameters

1.4.9. Set non-MC call blocking operation

1.4.9.i. Definition

Message	Requirement	Direction
blockNonMCCallsRequest	Mandatory	SDK ➔ IAPI
blockNonMCCallsResponse	Mandatory	IAPI ➔ SDK

Table 99: Set non-MC call blocking operation

1.4.9.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
block	M	1	Integer	0 to remove blocks, 1 to block incoming, 2 to block outgoing, 3 to block all non-MC calls

Table 100: Set non-MC call blocking parameters

1.4.10. Get device identity operation

1.4.10.i. Definition

Message	Requirement	Direction
getDeviceIdentityRequest	Mandatory	SDK ➔ IAPI
getDeviceIdentityResponse	Mandatory	IAPI ➔ SDK

Table 101: Get device identity operation

1.4.10.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
slotId	M	1	Integer	UICC card slot number

Table 102: Get device identity input parameters

1.4.10.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	O	1	String	the IMEI, or nothing if not present

Table 103: Get device identity output parameters

1.4.11. Get subscriber identity operation

1.4.11.i. Definition

Message	Requirement	Direction
getSubscriberIdentityRequest	Mandatory	SDK ➔ IAPI
getSubscriberIdentityResponse	Mandatory	IAPI ➔ SDK

Table 104: Get subscriber identity operation

1.4.11.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
slotId	M	1	Integer	UICC card slot number

Table 105: Get subscriber identity input parameters

1.4.11.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	O	1	String	the IMSI, or nothing if not present

Table 106: Get subscriber identity output parameters

1.4.12. Get IMS private user identity operation

1.4.12.i. Definition

Message	Requirement	Direction
getImpiRequest	Mandatory	SDK ➔ IAPI
getImpiResponse	Mandatory	IAPI ➔ SDK

Table 107: Get IMS private user identity operation

1.4.12.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
slotId	M	1	Integer	UICC card slot number

Table 108: Get IMS private user identity input parameters

1.4.12.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	O	1	String	the IMPI, or nothing if not present

Table 109: Get IMS private user identity output parameters

1.4.13. Get IMS user identities operation

1.4.13.i. Definition

Message	Requirement	Direction
getImpuRequest	Mandatory	SDK ➔ IAPI
getImpuResponse	Mandatory	IAPI ➔ SDK

Table 110: Get IMS user identities operation

1.4.13.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
slotId	M	1	Integer	UICC card slot number

Table 111: Get IMS user identities input parameters

1.4.13.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	O	1..N	String	an array of IMPU strings, with one IMPU per string, or nothing if not present

Table 112: Get IMS user identities output parameters

1.4.14. Get IMS home network domain operation

1.4.14.i. Definition

Message	Requirement	Direction
getDomainRequest	Mandatory	SDK ➔ IAPI
getDomainResponse	Mandatory	IAPI ➔ SDK

Table 113: Get IMS home network domain operation

1.4.14.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
slotId	M	1	Integer	UICC card slot number

Table 114: Get IMS home network domain input parameters

1.4.14.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	O	1	String	IMS domain name, or nothing if not present

Table 115: Get IMS home network domain output parameters

1.4.15. Get PCSCF operation

1.4.15.i. Definition

Message	Requirement	Direction
getPcscfRequest	Mandatory	SDK ➔ IAPI
getPcscfResponse	Mandatory	IAPI ➔ SDK

Table 116: Get PCSCF operation

1.4.15.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
slotId	M	1	Integer	UICC card slot number

Table 117: Get PCSCF input parameters

1.4.15.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	O	1..N	String	an array of PCSCF strings with one PCSCF per string, or nothing if not present

Table 118: Get PCSCF output parameters

1.4.16. Get PCSCF from PCO operation

1.4.16.i. Definition

Message	Requirement	Direction
getPcscfPcoRequest	Mandatory	SDK ➔ IAPI
getPcscfPcoResponse	Mandatory	IAPI ➔ SDK

Table 119: Get PCSCF from PCO operation

1.4.16.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
type	M	1	String	Type of the previously created MC PTT APN

Table 120: Get PCSCF from PCO input parameters

1.4.16.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	O	1..N	String	an array of PCSCF strings with one PCSCF per string, or nothing if not present

Table 121: Get PCSCF address from PCO output parameters

1.4.17. Get SIM authentication response operation

1.4.17.i. Definition

Message	Requirement	Direction
getAuthenticationRequest	Mandatory	SDK ➔ IAPI
getAuthenticationResponse	Mandatory	IAPI ➔ SDK

Table 122: Get SIM authentication response operation

1.4.17.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
slotId	M	1	Integer	UICC card slot number
appType	M	1	Integer	Application type
authType	M	1	Integer	Authentication type
data	M	1	String	Authentication challenge data, base64 encoded. See 3GPP TS 31.102/31.103 7.1.2 for more details.

Table 123: Get SIM authentication response input parameters

1.4.17.iii. Output parameters

Parameter Name

Qualifier

Cardinality

Data type

Description

result

String

the response of SIM authentication, base64 encoded,

or nothing if not available.

Table 124: Get SIM authentication response output parameters

1.4.18. Read configuration file operation

1.4.18.i. Definition

Message	Requirement	Direction
readConfigurationFileRequest	Mandatory	SDK ➔ IAPI
readConfigurationFileResponse	Mandatory	IAPI ➔ SDK

Table 125: Read configuration file operation

1.4.18.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
storage	M	1	Integer	configuration file storage
type	M	1	Integer	configuration file type

Table 126: Read configuration file input parameters

1.4.18.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	O	0..N	Byte	An array of byte data, or nothing if file is not present

Table 127: Read configuration file output parameters

1.4.19. Write configuration file operation

1.4.19.i. Definition

Message	Requirement	Direction
writeConfigurationFileRequest	Mandatory	SDK ➔ IAPI
writeConfigurationFileResponse	Mandatory	IAPI ➔ SDK

Table 128: Read configuration file operation

1.4.19.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
storage	M	1	Integer	configuration file storage
type	M	1	Integer	configuration file type
data	M	0..N	Byte	an array of byte data to write

Table 129: Read configuration file input parameters

1.4.19.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	M	1	Boolean	true if write was successful, false otherwise

Table 130: Read configuration file output parameters

1.4.20. Check package authentication operation

1.4.20.i. Definition

Message	Requirement	Direction
checkPackageAuthRequest	Mandatory	SDK ➔ IAPI
checkPackageAuthResponse	Mandatory	IAPI ➔ SDK

Table 131: Check package authentication operation

1.4.20.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
pkgname	M	1	String	Full name of the package

Table 132: Check package authentication input parameters

1.4.20.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	M	1	Boolean	true if the given package is trusted, false otherwise

Table 133: Check package authentication output parameters

1.4.21. Check UID authentication operation

1.4.21.i. Definition

Message	Requirement	Direction
checkUidAuthRequest	Mandatory	SDK ➔ IAPI
checkUidAuthResponse	Mandatory	IAPI ➔ SDK

Table 134: Check UID authentication operation

1.4.21.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
uid	M	1	String	UID to check

Table 135: Check UID authentication input parameters

1.4.21.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
result	M	1	Boolean	true if the given UID is trusted, false otherwise

Table 136: Check UID authentication output parameters

1.4.22. Application registration for eMBMS operation

1.4.22.i. Definition

This operation allows the SDK to register itself within the eMBMS plugin, and provide the callback listeners to be used for notifications related to location (MBMS SAI list change, cell change), to MBMS bearer monitoring (availability, quality) and consumption.

Message	Requirement	Direction
ApplicationRegistrationRequest	Mandatory	SDK ➔ IAPI
ApplicationRegistrationResponse	Mandatory	IAPI ➔ SDK

Table 137: Application registration

1.4.22.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
CallbackListener	M	1	Listener	Listener for the notifications sent by the eMBMS plugin

Table 138: location listener registration input parameters

1.4.22.iii. Output parameters

None

1.4.23. Application deregistration for eMBMS operation

1.4.23.i. Definition

This operation allows the SDK to deregister itself from the eMBMS plugin. The eMBMS interrupts all operations previously requested by the SDK (e.g. MBMS bearer monitoring or consumption) and deletes any parameters and/or internal state associated to this application. For Android implementation the Application is deregistered as soon as the Application call unbindService().

Message	Requirement	Direction
ApplicationDeregistrationRequest	Mandatory	SDK ➔ IAPI
ApplicationDeregistrationResponse	Mandatory	IAPI ➔ SDK

Table 139: Application deregistration

1.4.23.ii. Input parameters

none

1.4.23.iii. Output parameters

none

1.4.24. Cell change notification operation

1.4.24.i. Definition

This operation is executed whenever the UE moves into a new cell, once the SDK has is registered (see 5.4.17).

Message	Requirement	Direction
CellInfoNotificationRequest	Mandatory	IAPI ➔ SDK
CellInfoNotificationResponse	Mandatory	SDK ➔ IAPI

Table 140: cell change notification operation

1.4.24.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
MCC	M	1	Integer	Mobile country code
MNC	M	1	Integer	Mobile network code
ECI	M	1	Integer	E-utran cell identifier

Table 141: cell change notification input parameters

1.4.24.iii. Output parameters

None

1.4.25. MBMS SAI list change notification operation

1.4.25.i. Definition

This operation is executed whenever the MBMS SAI list (given by the SIB 15) is updated, once the SDK has is registered (see 5.4.17).

Message	Requirement	Direction
MBMSSAIListNotificationRequest	Mandatory	IAPI ➔ SDK
MBMSSAIListNotificationResponse	Mandatory	SDK ➔ IAPI

Table 142: MBMS SAI list change notification

1.4.25.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
SAI	M	0..n	Integer	MBMS service area id

Table 143: MBMS SAI list change notification input parameters

1.4.25.iii. Output parameters

none

1.4.26. MBMS Group communication monitoring start operation

1.4.26.i. Definition

This operation allows the SDK to subscribe to monitoring events (MBMS bearer availability, reception quality estimation) related to a MBMS bearer delivering mission critical services.

Message	Requirement	Direction
Group Communication monitoring start request	Mandatory	SDK ➔ IAPI
Group Communication monitoring stop response	Mandatory	IAPI ➔ SDK

Table 144: group communication monitoring start

1.4.26.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
TMGI	M	1	Integer	Identifier of the MBMS bearer
SAI	O	1..n	Integer	List of MBMS SAI where this MBMS is delivered. If the SIB15 is broadcasted, this list is used to determine the frequencies where could MBMS bearer should be found.
frequencies	O	1..n	Integer	List of frequencies (earcfn) where this MBMS bearer is be delivered. Used if the SIB15 is not delivered, or if the SAI parameter is not provided.
QCI	O	1	Integer	Quality Class Identifier. If present, indicates which threshold for the packet loss rate should be considered for reception quality notification (QCI 65 for MCPTT, see 23.203)

Table 145: group communication registration input parameters

1.4.26.iii. Output parameters

none

1.4.27. MBMS Group communication monitoring stop operation

1.4.27.i. Definition

This operation allows the SDK to unsubscribe to monitoring events (MBMS bearer availability, reception quality estimation) related to a MBMS bearer delivering mission critical services.

Message	Requirement	Direction
Group Communication monitoring stop request	Mandatory	SDK ➔ IAPI
Group Communication monitoring stop response	Mandatory	IAPI ➔ SDK

Table 146: group communication monitoring top

1.4.27.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
TMGI	M	1	Integer	Identifier of the MBMS bearer

Table 147: group communication monitoring start input parameters

1.4.27.iii. Output parameters

none

1.4.28. MBMS Group communication status change notification operation

1.4.28.i. Definition

This operation is executed:

· when the MBMS bearer availability changes, i.e. the TMGI is found in the (SC-) MCCH and is not suspended.

· when the reception quality estimation changes

Message	Requirement	Direction
groupCommStatusChangeRequest	Mandatory	IAPI ➔ SDK
groupCommStatusChangeResponse	Mandatory	SDK ➔ IAPI

Table 148: Group communication status change notification

1.4.28.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
TMGI	M	1	Integer	Identifier of the MBMS bearer
availability	M	1	Boolean	Indicates if the MBMS bearer is available within the UE location, i.e. the TMGI is found in the (SC-) MCCH and is not suspended.
Quality estimation	O	1	Boolean	Indicates if the quality is estimated good enough to consume MC services, based on the QCI given the registration.

Table 149: Group communication status change notification input parameters

1.4.28.iii. Output parameters

None

1.4.29. MBMS Group communication open operation

1.4.29.i. Definition

This operation allows the SDK to consume a MC service delivered over MBMS.

Message	Requirement	Direction
GroupCommOpenRequest	Mandatory	SDK ➔ IAPI
GroupCommOpenResponse	Mandatory	IAPI ➔ SDK

Table 150: group communication open

1.4.29.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
TMGI	M	1	Integer	Identifier of the MBMS bearer
SAI	O	1..n	Integer	List of MBMS SAI where this MBMS is delivered. If the SIB15 is broadcasted, this list is used to determine the frequencies where could MBMS bearer should be found.
Frequencies	O	1..n	Integer	List of frequencies (earcfn) where this MBMS bearer is be delivered. Used if the SIB15 is not delivered, or if the SAI parameter is not provided.

Table 151: group communication open input parameters

1.4.29.iii. Output parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
NetworkInterface	O	M	String	Name of the network interface where the packets are made available by the application.

Note : this response is asynchronous and provided by notification.

1.4.30. MBMS Group communication close operation

1.4.30.i. Definition

This operation allows the SDK to consume a MC service delivered over MBMS.

Message	Requirement	Direction
GroupCommCloseRequest	Mandatory	SDK ➔ IAPI
GroupCommCloseResponse	Mandatory	IAPI ➔ SDK

Table 152: group communication response

1.4.30.ii. Input parameters

Parameter Name	Qualifier	Cardinality	Data type	Description
TMGI	M	1	Integer	Identifier of the MBMS bearer

Table 153: group communication close parameters

1.4.30.iii. Output parameters

None