API Description for Extended Web Services

Messaging

The following sections provide detailed information about the Messaging service capability:

• Web Service
• Listener interface

 

---

Web Service

The messaging Web Service provides an application with functions for sending and receiving SMS, MMS, and e-mail messages.

closeMailBox

Closes a previously opened mailbox.

Table 7-1 closeMailBox(mailboxTicket)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	Identifier for the mailbox as retrieved when openMailbox was invoked. See openMailbox.
Returns
Void.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

deleteMessages

Deletes one or more messages from a mailbox folder.

Table 7-2 deleteMessages(mailboxTicket, folder, messageID, requesterID)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	Identifier for the mailbox as retrieved when openMailbox was invoked. See openMailbox.
folder	impl:MailboxFolder	See MailboxFolder. The folder the message is stored in.
messageID	impl:ArrayOf_xsd_string	See ArrayOf_xsd_string.
requesterID	xsd:string	Application ID as provided by the operator.
Returns
Void.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

disableMessagingNotification

Disables a previously subscription for notifications on events related to a mailbox.

Table 7-3 disableMessagingNotification(notificationTicket)

Parameter Name	Type	Description
Input
notificationTicket	xsd:string	Identifier for the notification listener as retrieved when enableMessagingNotification was invoked. See enableMessagingNotification.
Returns
Void.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

enableMessagingNotification

Subscribes for notifications on events related to a mailbox.

Table 7-4 enableMessagingNotification(endPoint, mailbox, mailboxPassword, notificationCriteria, serviceCode, requesterID)

Parameter Name	Type	Description
Input
endpoint	xsd:string	The URL to the Web Service that implements the listener interface. See Listener interface. An example is http://www.acompany.com/axis/services/MessagingListener
mailbox	xsd:string	The ID of the mailbox to subscribe for notifications on.
mailboxPassword	xsd:string	The password associated with the mailbox.
notificationCriteria	impl:NotificationCriteria	See NotificationCriteria. Defines which events to subscribe for notifications on.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
enableMessagingNotificationReturn	xsd:string	ID of the request. This ID is supplied in newMessageAvailable to keep track of the different request-response pairs.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

getMMS

Gets an MMS from the mailbox. The message is returned as an SOAP attachment in mime format.

Table 7-5 getMMS(mailboxTicket, folder, messageID, requesterID)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	ID of the mailbox as retrieved when openMailbox was invoked. See openMailbox.
folder	impl:MailboxFolder	See MailboxFolder. The folder the message is stored in.
messageID	xsd:string	ID of the message as given in newMessageAvailable.
requesterID	xsd:string	The application ID as given by the operator.
Returns
Void
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

getMessageProperties

Gets properties of a message. Properties includes originator address, destination address, subject, and so on.

Table 7-6 getMessageProperties(mailboxTicket, folder, messageID, propertyTypes, requesterID)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	Identifier for the mailbox as retrieved when openMailbox was invoked.
folder	impl:MailboxFolder	See MailboxFolder. The folder the message is stored in.
messageID	xsd:string	ID of the message as given in newMessageAvailable.
propertyTypes	impl:ArrayOfMessagingPropertyName	See ArrayOfMessagingPropertyName. Defines which properties to get.
requesterID	xsd:string	The application ID as given by the operator.
Returns
getMessagePropertiesReturn		impl:ArrayOfMessagingProperty. See ArrayOfMessagingProperty. Properties for the message.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

getSMS

Fetches an SMS from the mailbox.

Table 7-7 getSMS(mailboxTicket, folder, messageID, requesterID)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	Identifier for the mailbox as retrieved when openMailbox was invoked.
folder	impl:MailboxFolder	See MailboxFolder. The folder the message is stored in.
messageID	xsd:string	ID of the message as given in newMessageAvailable.
requesterID	xsd:string	The application ID as given by the operator.
Returns
getSMSReturn	xsd:string	The message text.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

listMessages

List messages in a mailbox folder.

Table 7-8 listMessages(mailboxTicket, folder, requesterID)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	Identifier for the mailbox as retrieved when openMailbox was invoked.
folder	impl:MailboxFolder	See MailboxFolder. The folder the message is stored in.
requesterID	xsd:string	The application ID as given by the operator.
Returns
listMessagesReturn	impl:ArrayOfMessageDescription	See ArrayOfMessageDescription. An array of message descriptions.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

listNewMessages

List unread messages in a mailbox folder.

Table 7-9 listNewMessages(mailboxTicket, folder, requesterID)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	Identifier for the mailbox as retrieved when openMailbox was invoked.
folder	impl:MailboxFolder	See MailboxFolder. The folder the message is stored in.
requesterID	xsd:string	The application ID as given by the operator.
Returns
listNewMessagesReturn	impl:ArrayOfMessageDescription	See ArrayOfMessageDescription. An array of message descriptions.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

openMailbox

Opens a mailbox. Returns a mailboxTicket to be used in messaging operations. The mailbox name and its associated password is provided by the operator.

Table 7-10 openMailbox(mailbox, password, requesterID)

Parameter Name	Type	Description
Input
mailbox	xsd:string	Name of the mailbox.
password	xsd:string	Password for the mailbox.
requesterID	xsd:string	The application ID as given by the operator.
Returns
openMailboxReturn	xsd:string	The mailboxTicket used in operations towards the mailbox.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

sendEMail

Sends an e-mail to one or more destination addresses. The message shall be provided as a SOAP attachment in mime format.

Table 7-11 sendEMail(mailboxTicket, messageProperties, serviceCode, requesterID)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	Identifier for the mailbox as retrieved when openMailbox was invoked.
messageProperties	impl:ArrayOfMessagingProperty	See ArrayOfMessagingProperty. Properties for the message. For example destination address and subject.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
sendEMailReturn	impl:ArrayOfMessageSendResult	See ArrayOfMessageSendResult. Contains information on identifier for the message, status of the message and so on for each destination address.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

sendMMS

Sends an MMS to one or more destination addresses. The message shall be provided as a SOAP attachment in mime format.

Table 7-12 sendMMS(mailboxTicket, messageProperties, serviceCode, requesterID)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	Identifier for the mailbox as retrieved when openMailbox was invoked.
messageProperties	impl:ArrayOfMessagingProperty	See ArrayOfMessagingProperty. Properties for the message. For example destination address and subject.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
sendMMSReturn	impl:ArrayOfMessageSendResult	See ArrayOfMessageSendResult. Contains information on identifier for the message, status of the message and so on for each destination address.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

sendSMS

Sends an SMS to one or more destination addresses. Message delivery status can be checked by reading the properties for the message IDs returned by this method.

Table 7-13 sendSMS(mailboxTicket, message, messageProperties, serviceCode, requesterID)

Parameter Name	Type	Description
Input
mailboxTicket	xsd:string	Identifier for the mailbox as retrieved when openMailbox was invoked.
messageProperties	impl:ArrayOfMessagingProperty	See ArrayOfMessagingProperty. Properties for the message. For example destination address.
message	xsd:string	The text of the message.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
sendSMSReturn	impl:ArrayOfMessageSendResult	See ArrayOfMessageSendResult. Contains information on identifier for the message, status of the message and so on for each destination address.
Exceptions
MessagingException		See MessagingException.
GeneralException		See GeneralException.

Exceptions

MessagingException

Exception of this type are raised when there are error conditions related to the messaging Web Service. Other error conditions are reported using the exception GeneralExcepetion.

GeneralException

This exception is raised when the applications session has expired or there are communication problems with the underlying platform.

Complex data types

ArrayOfMessageDescription

Array of message descriptions. See MessageDescription for information on the individual records in the array.

ArrayOfMessageSendResult

Array of results of a result of a message send operation. See MessageSendResult for information on the individual records in the array.

ArrayOfMessagingProperty

Array of message properties. See MessagingProperty for information on the individual records in the array.

ArrayOfMessagingPropertyName

Array of message property names. See MessagingPropertyName for information on the individual records in the array.

ArrayOf_xsd_string

Array of strings.

ContentType

Content type defined for MMS messages. Enumeration (xsd:string) with the following values:

Table 7-14

Value	Description
CT_UNDEFINED	Undefined content type.
CT_APPLICATION_MULTIPART_MIXED	MIME multiparty/mixed.
CT_APPLICATION_MULTIPART_RELATED	MIME multiparty/related.
CT_APPLICATION_SMIL	SMIL
CT_IMAGE_GIF	GIF image.
CT_IMAGE_JPEG	JPEG image
CT_IMAGE_PNG	PNG image.
CT_IMAGE_TIFF	TIFF image.
CT_IMAGE_WBMP	WAP BMP image.
CT_TEXT_HTML	HTML.
CT_TEXT_PLAIN	Plain text.
CT_TEXT_WML	WAP Mark-up language.
CT_AUDIO_AMR	AMR audio.
CT_AUDIO_WAVE	Wave audio.
CT_AUDIO_MP3	MP3 audio.
CT_AUDIO_AU	AU audio.
CT_AUDIO_AIF	AIF audio.
CT_AUDIO_SND	SND audio.
CT_AUDIO_RA	RA audio.
CT_AUDIO_MID	MIDI audio.

MailboxFolder

Defines the folders in a mailbox. Enumeration (xsd:string) with the following values.

Table 7-15

Value	Description
MESSAGE_MAILBOX_UNDEFINED	Undefined mailbox folder.
MESSAGE_MAILBOX_OUTBOX	Outbox folder.
MESSAGE_MAILBOX_INBOX	Inbox folder.
MESSAGE_MAILBOX_DRAFTS	Draft folder.
MESSAGE_MAILBOX_TRASH	Trash folder.
MESSAGE_MAILBOX_TEMPLATES	Templates folder.

MessageDescription

Contains the ID for a message and the type of message.

Table 7-16

Name	Type	Description
messageId	xsd:string	ID of the message.
format	intf:MessageFormatType	See MessageFormatType,

MessageFormatType

Information on the format of a message. Enumeration (xd:string) with one of the following values.

Table 7-17

Value	Description
MESSAGE_FORMAT_AU	Audio message.
MESSAGE_FORMAT_BINARY	Binary message.
MESSAGE_FORMAT_MIME	MIME message.
MESSAGE_FORMAT_MM	Multimedia message.
MESSAGE_FORMAT_TEXT	Text message.
MESSAGE_FORMAT_UNDEFINED	Undefined.
MESSAGE_FORMAT_UUENCODED	UU-encoded message.
MESSAGE_FORMAT_WAVE	Wave audio message.

MessageSendResult

Information about the result of a send message operation for an individual destination address.

Table 7-18

Name	Type	Description
address	xsd:string	Destination address, in URI format (tel:<address>), (MSISDN or e-mail address).
messageID	xsd:string	ID of the message.
sendStatus	intf:MessageSendStatus	See MessageSendStatus.

MessageSendStatus

Defines the status of a message. Enumeration (xsd:string) with one of the following values.

Table 7-19

Value	Description
MESSAGE_SEND_OK	The message was successfully sent.
MESSAGE_SEND_ERROR	An error occurred when the message was sent.

MessageStatusType

Definition of statuses a message can have. Enumeration (xsd:string) with the following values.

Table 7-20

Value	Description
MESSAGE_STATUS_UNDEFINED	Undefined.
MESSAGE_STATUS_READ_MESSAGE	Read.
MESSAGE_STATUS_UNREAD_MESSAGE	Unread.
MESSAGE_STATUS_FORWARDED_MESSAGE	Has been forwarded to another address.
MESSAGE_STATUS_REPLIED_TO_MESSAGE	Has been replied to.
MESSAGE_STATUS_SAVED_OR_UNSENT_MESSAGE	Saved or not yet sent.
MESSAGE_STATUS_NOTIFICATION_THAT_A_ MESSAGE_WAS_DELIVERED	Delivered to destination address(es).
MESSAGE_STATUS_NOTIFICATION_THAT_A_ MESSAGE_WAS_READ	Destination addressee has read the message.
MESSAGE_STATUS_NOTIFICATION_THAT_A_ MESSAGE_WAS_NOT_DELIVERED	Message was not delivered to the destination.
MESSAGE_STATUS_NOTIFICATION_THAT_A_ MESSAGE_WAS_NOT_READ	Message is not read.

MessagingException

Table 7-21

Name	Value	Description
exceptionMessage	xsd:string	Error message in text-format.
errorCode	xsd:int	Error code.

MessagingProperty

Table 7-22

Name	Type	Description
messagingPropertyName	intf:MessagingPropertyName	See MessagingPropertyName.
value	xsd:anyType	See MessagingPropertyName for which data type that corresponds to which MessagingPropertyname.

MessagingPropertyName

Properties of a message. Enumeration (xsd:string) with the following values.

Table 7-23

Value	Description
MESSAGE_UNDEFINED	Undefined. Null.
MESSAGE_ID	ID of the message. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_SUBJECT	Subject of the message. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_DATE_SENT	Date when the message was sent. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_DATE_RECEIVED	Date the message was received. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_DATE_CHANGED	Date the message was changed. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_SENT_FROM	Originator address. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_SENT_TO	Destination address. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_CC_TO	Carbon copy address. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_BCC_TO	Blind carbon copy address. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_SIZE	Size of the message. Use xsd:int in xsd:anyType in MessagingProperty.
MESSAGE_PRIORITY	Priority the message was sent with. Use Priority in xsd:anyType in MessagingProperty.
MESSAGE_FORMAT	Format of the message. Use MessageFormatType in xsd:anyType in MessagingProperty.
MESSAGE_STATUS	Status of the message. Use MessageStatusType in xsd:anyType in MessagingProperty.
MESSAGE_VALIDITY_PERIOD	Validity period of the message. Use xsd:string in xsd:anyType in MessagingProperty.
MESSAGE_ENCODING_TYPE	Encoding type of the message. Use xsd:string in xsd:anyType in MessagingProperty.

Priority

Priority of a message. Enumeration (xsd:string) with one of the following values.

Table 7-24

Value	Description
LOW	Low priority.
HIGH	High priority.
NORMAL	Normal priority.

MmsContent

Defines the content of an individual part of an MMS.

Table 7-25

Name	Type	Description
data	xsd:byte	Binary part of an element in an MMS message.
type	intf:ContentType	See ContentType.The type of content in the data field.
contentID	xsd:string	ID of the content.

MmsMessage

Container for content and properties for an MMS.

Table 7-26

Name	Type	Description
content	intf:MmsContent	See MmsContent.
properties	intf:MessagingProperty	See MessagingProperty.

NotificationCriteria

Defines for which events notifications shall be sent to a listener.

Enumeration (xsd:string) with one of the values.

Table 7-27

Value	Description
NC_NEW_MESSAGE_ARRIVED	Send notification when a new message arrives to the inbox folder.
NC_MESSAGE_DELIVERED_ACK	Send notification when a delivery acknowledgment has arrived.

 

---

Listener interface

The messaging listener interface defines the methods that the underlying platform invokes on a Web Service that is implemented by an application. When an application performs asynchronous requests from the messaging Web Service, the responses are delivered according to this interface.

deactivate

Used by the underlying system to inform the application that the session identified by notificationTicket is no longer valid. The application can not use the session no more.

Table 7-28 deactivate(notificationTicket)

Parameter Name	Type	Description
Input
notificationTicket	xsd:string	ID of the session. The ID was returned when MessagingProperty was invoked.
Returns
Void.
Exceptions
-

messageDeliveryAck

Message delivery receipts for messages are reported using this method.

Table 7-29 messageDeliveryAck(notificationTicket, messageId, messageStatus)

Input
notificationTicket	xsd:string	A ticket identifying the notification session.
messageId	xsd:string	ID of the message.
messageStatus	impl:MessageStatusType	See MessageStatusType.
Returns
Void.
Exceptions
-

newMessageAvailable

Information on arrival of new messages is reported using this method.

Table 7-30 newMessageAvailable(notificationTicket, mailbox, folder, messageDescr)

Parameter Name	Type	Description
Input
notificationTicket	xsd:string	ID of the session. This ticket was given when enableMessagingNotification was invoked.
mailbox	xsd:string	ID of the mailbox that holds a new message.
folder	impl:MailboxFolder	See MailboxFolder. The folder the new message is stored in.
messageDescr	impl:MessageDescription	See MessageDescription. Description of the message.
Returns
Void.
Exceptions
-

Complex data types

A subset of the ones described in Complex data types.