/pps/services/cellular/sms/control_private

General purpose SMS related functions

Publishers
The SMS service
Subscribers
Clients of the SMS service
Note: This type of object is known as a server object, a special PPS object designed for point-to-point communication between a server and one or more clients. For details, see "Server objects" in the Persistent Publish/Subscribe Developer's Guide.

Message/response format

Commands sent to the /pps/services/cellular/sms/control_private object are of the form:

msg::command_string\nid::msg_ID\ndat:json:{JSON_data}

Responses always reflect the command_string and msg_ID that were sent in the message, along with any errors: 

res::command_string
id::msg_ID
dat:json:{JSON_data}
error::error_description

send_message command

Transmit an SMS message.

The send_message command has the following format:

msg::send_message
id::msg_ID
dat:json:
{
    "recipientAddress":"recipient_address",
    "payload":"message_payload",
    "encoding":"gsm0338",
    "keepConnectionAlive":true|false,
    "typeOfNumber":reply_number_type,
    "numberingPlan":numbering_plan,
    "destinationPort":destination_port,
    "originatorPort":originator_port,
    "disableConcatenation":true|false
}

The parameters are as follows:

recipientAddress
Required. SMS message recipient's phone number.
payload
Required. The payload is passed as hex-encoded binary data through PPS based upon the specified encoding scheme.
encoding

Required. The character encoding that the message payload must be transcoded to before transmission. Currently, the only supported option is gsm0338 (GSM 7-bit character encoding, 7 bits per character).

keepConnectionAlive
An optional Boolean that, when true, indicates that the connection should be kept alive for several seconds and for consecutive send_message commands. If not present, it's assumed to be false. Not required for concatenated SM (forced to true).
typeOfNumber
Optional. Indicates the type of number (0 - 7) that must be used to reply to this message.
numberingPlan
Optional. Indicates the numbering plan (0 - 15) that must be used to reply to this message.
destinationPort
Optional. If present, defines the destination/receiving port (i.e., application in the receiving device) of the message. If not present, no port value is used. If present without the originatorPort optional parameter, originatorPort is set to 0 in the message.
originatorPort
Optional. If present, defines the originator/sending port (i.e., application in the sending device) of the message. If not present, no port value is used. If present without the destinationPort optional parameter, destinationPort is set to 0 in the message.
disableConcatenation
Optional. Supported for gsm0338 only. If present and true, this parameter causes the SMS service to segment the message at 160 characters and not add any parameters to the User Data Header (UDH). If not present or false, the SMS service uses the default concatentation in the UDH, allowing the receiving entity to stitch the messages together.

send_message response

The SMS service sends the send_message response in reply to a send_message command. The response has the following form:

res::send_message
id::msg_ID
dat:json:
{
    "messageId":SMS_message_ID
}
success::true|false
err::error_code
errstr::error_details

The following parameters and attributes may be returned in the response:

messageID
The messageID of the origianl send_message command. When the success parameter is false, the messageId attribute is invalid. It's the client's responsibility to retry sending the message following such failures.
success
Indicates whether the message was successfully sent, and is either true (no error) or false (an error occured).
err
The code of the error that occurred:
missing_argment
A required argument can't be decoded. The errstr attribute specifies the argument.
invalid_value
An argument is invalid. The errstr attribute provides more details about the invalid argument.
service_is_busy
The SMS service is currently trying to transmit a message. The client should wait for a service ready broadcast before sending another send_message command.
radio_failure
The radio driver reported a failure of the send operation.
errstr
Details about the error, if any.

receive_message message

The SMS service sends the receive_message notification to the client after receiving an SMS message. The receive_message notification has the following format:

msg::receive_message
dat:json:
{
    "messageId":SMS_msg_ID,
    "senderAddress":"sender_address",
    "payload":"msg_payload",
    "encoding":"encoding",
    "class":msg_class,
    "simIndices":[index1, index2, ...],
    "replacementType":msg_replacementType,
    "serviceCenterTimeStamp":"UTC_timestamp",
    "applicationPort":msg_receiving_port,
    "originatingApplicationPort":msg_originating_port,
    "typeOfNumber":reply_type,
    "numberingPlan":msg_numbering_plan,
    "path":msg_path,
    "totalSegments":msg_total_segments,
    "receivedSegments":msg_received_segments,
}

The parameters are as follows:

messageId
Required. A 32-bit integer used to identify messages received via SMS service. The client should keep this ID to match up the message with future updates.
senderAddress
Required. The phone number of the SMS message's sender.
payload
Required. The payload is passed as a UTF-8 string or hex-encoded binary data through PPS. If the message consists of multiple segments, the SUB character (0x1A) is used to represent segments that have not been received.
encoding
Required. The character encoding of the message payload. Possible values are utf-8 and unencoded. The unencoded value means the payload is hex-encoded binary data.
class
Required. Represents the class of an the incoming short message. The possible values are:
  • 0—The SMS message is displayed on the mobile screen without being saved in the message store or on the SIM card.
  • 1—The SMS message is stored in the device memory or the SIM card.
  • 2—The SMS message carries SIM card data. The SIM card data must be successfully transferred prior to sending acknowledgment to the service center. An error message is sent to the service center if this transmission is not possible.
  • 3—The SMS message is forwarded to an external device. The delivery acknowledgment is always sent to the service center (even if the message isn't forwarded).
  • 4—No class specified.
simIndices
Optional. The list of indexes at which the message segments (each segment is a short message) are stored on the SIM card.
replacementType
Optional. Indicates that this message replaces another message from the same sender address, and with the same protocol identifier (PID).
serviceCenterTimeStamp
Optional. The UTC time when the SMS service center received the message. The value is a decimal number.
applicationPort
Optional. Indicates that a receiving port (i.e., application in the receiving device) has been defined in the short message. This field is present only if included in the message.
originatingApplicationPort
Optional. Indicates that a sending port (i.e., application in the sending device) has been defined in the short message. This field is present only if included in the message. Allowed values are 0 to 65535.
typeOfNumber
Optional. Indicates the type of number that must be used to reply to this message. This field is present only if this value must be used. Allowed values are 0 to 7.
numberingPlan
Optional. Indicates the numbering plan that must be used to reply to this message. This field is present only if this value must be used. Allowed values are 0 to 15.
path
Optional. Indicates the framework the message was received over. Allowed values are 1 (cellular) and 2 (IMS).
totalSegments
Optional. Total number of segments expected to be delivered with this message ID. Allowed valures are 1 to 255.
receivedSegments
Optional. The number of segments that have been received with this message ID. When this value reaches totalSegments, the message is complete. Allowed values are 1 to 255.

register_message_filter_listener command

Register the client as the only listener of the SMS filter.

A filter consists of either a port or a sender address, but never both. To ensure mutual exclusion between filters created by different listeners, each filter requires either a port or a sender address to be specified.

Current settings limit the total number of filters to 32, not including the default text port.

The register_message_filter_listener command has the following form:

msg::register_message_filter_listener
id::msg_ID
dat:json:
{
    "senderAddress":"sender_address",
    "port":port_number
}

The parameters are as follows:

senderAddress
The basic string address against which the sender address parameter is matched in filtering text messages. Max length is 48 characters.
port
The port number requested by the client. Currently, the supported port is 0xdeadbeef. This port receives all incoming short messages that are not addressed to any other port. Text messages fall into this group. The client that needs to receive and process text messages should register as the listener of this port.

register_message_filter_listener response

The UICC service sends the register_message_filter_listener response to the client in reply to the register_message_filter_listener command. The response has the following form:

res::register_message_filter_listener
id::msg_ID
dat:json:
{
    "messageFilterId":filter_id
}
success::true|false
err::error_code_string
errstr::error_details

The following parameters and attributes may be returned in the response:

messageFilterId
Unique ID given by the service upon successful registration of a message filter. Each identifier uniquely identifies a single filter in the service, allowing the listener to deregister that specific filter. A value of -1 indicates and error; a value that's >=0 indicates a successful registration.
success
Indicates whether the operation was successfule (true = success; false = an error occurred).
err
One of the following codes may be returned in the err attribute in the case of an error:
  • missing_argument—One or more parameters are missing or can't be successfully decoded.
  • filter_is_busy—The specified filter currently has another registered listener.
  • no_permission—The client doesn't have permission to register as a text filter listener.
  • port_is_busy—The specified port currently has another registered listener.
  • out_of_resources—The SMS service doesn't have sufficient resources to register another text filter listener.
  • regex_error—An error has occurred in a regular expression preparation. The errstr attribute provides more details.
  • invalid_value—The specified port value isn't within the acceptable range for SMS.
errstr
Details about the error, if available.