API Description for Parlay X

Multimedia Message

The following sections describe the Multimedia message API used for sending and receiving multimedia messages such as MMS:es:

Send Message API

sendMessage

Send an MMS or e-mail to one or several destinations.

Table 7-1 sendMessage(destAddressset, senderAddress, subject, priority, charging) Attachment[content]

Parameter Name	Type	Description
Input
destAddressset	EndUserIdentifier[]	Array of EndUserIdentifier. MSISDN of the destination terminal(s).
senderAddress	String	Format is <mailbox ID>\<mailbox password>\tel:<originator address> Mailbox ID and password are supplied by the service provider. Example: "50000\apassword\tel:+46541768700"
subject	String	OPTIONAL. Subject of the message.
priority	MessagePriority	OPTIONAL. Represents the priority of the message. If not defined, the network will assign a priority based on an operator policy.
charging	String	OPTIONAL. Represents the name of an operator-specific charging plan that defines who to charge for the message and how much. If the named charge plan does not exist, the InvalidArgumentException is thrown. If no charge plan is specified, the sending service/application will be charged, based on operator-specific charging policy.
Attachment[content]	MIME or DIME	Data to be sent with the message, that is MIME or DIME format. Note: Sent as a SOAP-Attachment. Not as a parameter in the SOAP envelope. When sending a SMIL message, the MIME content ID in the attachment must be the same as the SMIL Content ID defined in the SMIL document. For example, if a text is defined as below in the SMIL document: `<par dur="2000ms"> <text src="Cid:MyText.txt" region="Image"> <param name="foreground-color" value="#000000"/> <param name="textsize" value="large"/> </text> </par>` The corresponding MIME Content ID (`MyText.txt`) shall be defined in the SOAP attachment.
Returns
	String	ID of the MMS delivery request.

Possible exceptions
UnknownEndUserException
ServiceException
InvalidArgumentException
MessageTooLongException
PolicyException

getMessageDeliveryStatus

Requests the status of a previous MMS delivery request identified by requestIdentifier.

Table 7-2 getMessageDeliveryStatus(requestIdentifier)

Parameter Name	Type	Description
Input
requestIdentifier	String	ID of the SMS delivery request.
Returns
	DeliveryStatusType[]	Array of DeliveryStatusType. Each entry in the array corresponds to a destination address as given when the message was sent. See DeliveryStatusType.

Possible exceptions
UnknownRequestIdentifierException
ServiceException

Receive message API

getReceivedMessages

Poll for new messages.

Table 7-3 getReceivedMessages(registrationIdentifier, priority)

Parameter Name	Type	Description
Input
registrationIdentifier	String	The mailbox. Format is <mailbox ID>\<mailbox password> Mailbox ID and password are supplied by the service provider. Example: "tel:50000\apassword"
priority	MessagePriority	OPTIONAL. The priority of the messages to poll from the Parlay X gateway. All messages of the specified priority and higher will be retrieved. If not specified, all messages are returned, that is, the same as specifying priority Low.
Returns
	MessageRef[]	Array of messages received.

Possible exceptions
InvalidArgumentException
ServiceException
PolicyException
UnknownRegistrationIdentifierException

getMessage

Reads a message. The data is returned as a SOAP-Attachment in the return message, not as a return parameter. The attachment is encoded according to MIME or DIME format.

Table 7-4 getMessage(messageRefIdentifier) Attachment[content]

Parameter Name	Type	Description
Input
messageRefIdentifier	String	ID of the message.
Attachment[content]		Data returned in the SOAP Header of the response to the SOAP/HTTP request. Note: Sent as a SOAP-Attachment in the response. Not as a parameter in the SOAP envelope.
Returns
Void

Possible exceptions
InvalidArgumentException
ServiceException
PolicyException
UnknownMessageException

Message notification API

notifyMessageReception

Notifies an application of an incoming MMS. This method must be implemented on the server-side of the Parlay X client.

WebLogic Network Gatekeeper must be aware of the location of the Web Service implementing this interface. The location of the web service is defined using OAM in WebLogic Network Gatekeeper.

Table 7-5 notifyMessageReception (registrationIdentifier, messageRef)

Parameter Name	Type	Description
Input
registrationIdentifier	String	ID of the mailbox.
messageRef	MessageRef	Contains information associated with the received message.
Returns
Void

Possible exceptions
InvalidArgumentException
ApplicationException
UnknownRegistrationIdentifierException

Data Types

Table 7-6 Data types specific for Messaging

Data type	Description
MessagePriority	The MessagePriority data type is an enumeration with the following values:
	Low	Low message priority.
	Normal	Normal message priority.
	High	High message priority.
DeliveryStatus	The DeliveryStatus data type is an enumeration with the following values:
	Delivered	Successful delivery
	DeliveryUncertain	Delivery status unknown: e.g. because it was handed off to another network.
	DeliveryImpossible	Unsuccessful delivery; the message could not be delivered before it expired.
	MessageWaiting	The message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states.
DeliveryStatusType	Structure containing the following parameters:
	destinationAddress	Address associated with the delivery status. The address field is coded as a URI. Datatype: EndUserIdentifier.
	deliveryStatus	Parameter indicating the delivery status. Datatype: DeliveryStatus
MessageRef	Structure containing the following parameters:
	messageRefIdentifier	OPTIONAL. Contains a reference to a message stored in the Parlay X gateway. If the message is pure text, this parameter is not present. Datatype: String.
	messageServiceActivationNumber	Number associated with the invoked Message service, that is the destination address used by the terminal to send the message. Datatype: String.
	senderAddress	Indicates message sender address. Datatype: EndUserIdentifier.
	subject	OPTIONAL. Indicates the subject of the received message. This parameter will not be used for SMS services. Datatype: String.
	priority	The priority of the message: default is Normal. Datatype: MessagePriority.
	message	OPTIONAL. If present, the messageRefIdentifier is not present and this parameter contains the whole message. The type of the message is always pure ASCII text in this case. The message will not be stored in the Parlay X gateway. Datatype: String.
MessageURI	Structure containing the following parameters:
	bodyText	Contains the message body if it is encoded as ASCII text. Datatype: String.
	fileReferences	Array of URL references to all the attachments in the Multimedia message. These are URLs to different files, e.g. GIF pictures or pure text files. Datatype: URL[].

Exceptions

Table 7-7 Exceptions specific for Messaging

ID	Exception	Description
MSG1000E	UnknownRequestIdentifierException	The Parlay X gateway did not recognize the requestIdentifier parameter. The message may have timed out or may have never been sent. This fault includes a string that provides additional information
MSG1001E	UnknownRegistrationIdentifierException	The provided registration identifier does not exist. This fault includes a string that provides additional information.
MSG1002E	UnknownMessageException	The provided messageRefIdentifier was not found in the Parlay X gateway. The message may have been timed out or it may never have been received by the gateway. This fault includes a string that provides additional information