SMS subscriber¶
The SMS subscriber module acts as a unique and global client in the system that can dispatch SMS notifications to many subscribers, which makes it possible for more than one module to receive SMS messages.
The module provides functions to register and unregister SMS listeners, which are the modules that need to send or receive SMS messages. Each listener is identified by a unique handle and receives the SMS data and metadata through a callback function. The module also provides a possibility to send SMS messages.
SMS listeners can be registered or unregistered at run time. The SMS data payload is parsed and processed before it is given to the client.
The SMS module uses AT commands to register as an SMS client to the modem. In addition, AT commands are also used to send SMS messages. SMS notifications are received using AT commands, but those are not visible for the users of this module. The module automatically acknowledges the SMS messages received on behalf of each listener.
The module does not use a dedicated socket. It uses the shared AT socket that is provided by the AT command notifications module.
The current modem firmware allows only one SMS client.
Configuration¶
Configure the following Kconfig options when using this library:
CONFIG_SMS
- Enables the SMS subscriber library.CONFIG_SMS_SUBSCRIBERS_MAX_CNT
- Sets the maximum number of SMS subscribers.CONFIG_AT_CMD_RESPONSE_MAX_LEN
- Defines the maximum size of the AT command response, which might limit the size of the received SMS message. Values over 512 bytes will not restrict the size of the received message as the maximum data length of the SMS is 140 bytes. This parameter is defined in the AT command interface module.
Limitations¶
Only a single SMS client can be registered to the modem in the system. If there is already an SMS client registered in the system (for example, using AT commands), the initialization of this module fails, and an error is returned.
API documentation¶
include/modem/sms.h
lib/sms/sms.c
-
group
sms
Public APIs of the SMS subscriber manager module.
Defines
-
SMS_MAX_PAYLOAD_LEN_CHARS
¶ Maximum length of SMS in number of characters as specified in 3GPP TS 23.038 Section 4 and Section 6.1.2.1.1.
-
SMS_MAX_ADDRESS_LEN_CHARS
¶ Maximum length of SMS address, i.e., phone number, in characters as specified in 3GPP TS 23.040 Section 9.1.2.3.
Typedefs
Enums
Functions
-
int
sms_register_listener
(sms_callback_t listener, void *context)¶ Register a new listener to SMS library.
Also registers to modem’s SMS service if it’s not already subscribed.
A listener is identified by a unique handle value. This handle should be used to unregister the listener. A listener can be registered multiple times with the same or a different context.
- Parameters
listener – [in] Callback function. Cannot be null.
context – [in] User context. Can be null if not used.
- Returns -EINVAL
Invalid parameter.
- Returns -ENOSPC
List of observers is full.
- Returns -EBUSY
Indicates that one SMS client has already been registered towards the modem and SMS subscriber module is not able to do it.
- Returns -ENOMEM
Out of memory.
- Returns
Handle identifying the listener, or a negative value if an error occurred.
-
void
sms_unregister_listener
(int handle)¶ Unregister a listener.
Also unregisters from modem’s SMS service if there are no listeners registered.
- Parameters
handle – [in] Handle identifying the listener to unregister.
-
int
sms_send_text
(const char *number, const char *text)¶ Send SMS message.
Sending is done with GSM 7bit encoding used to encode textual SMS messages. SMS-SUBMIT message is specified in 3GPP TS 23.040 Section 9.2.2.2 and data encoding in 3GPP TS 23.038 Section 4 and Section 6.2. This function doesn’t support sending of 8bit binary data messages or UCS2 encoded text.
- Parameters
number – [in] Recipient number.
text – [in] Text to be sent.
- Returns -EINVAL
Invalid parameter.
- Returns
0 on success, otherwise error code.
-
struct
sms_time
¶ - #include <sms.h>
SMS time information specified in 3GPP TS 23.040 Section 9.2.3.11.
-
struct
sms_address
¶ - #include <sms.h>
SMS address, i.e., phone number.
This may represent either originating or destination address and is specified in 3GPP TS 23.040 Section 9.1.2.5.
-
struct
sms_udh_concat
¶ - #include <sms.h>
SMS concatenated short message information.
This is specified in 3GPP TS 23.040 Section 9.2.3.24.1 and 9.2.3.24.8.
Public Members
-
bool
present
¶ Indicates whether this field is present in the SMS message.
-
uint16_t
ref_number
¶ Concatenated short message reference number.
-
uint8_t
total_msgs
¶ Maximum number of short messages in the concatenated short message.
-
uint8_t
seq_number
¶ Sequence number of the current short message.
-
bool
-
struct
sms_udh_app_port
¶ - #include <sms.h>
SMS application port addressing information.
This is specified in 3GPP TS 23.040 Section 9.2.3.24.3 and 9.2.3.24.4.
-
struct
sms_deliver_header
¶ - #include <sms.h>
SMS-DELIVER message header.
This is for incoming SMS message and more specifically SMS-DELIVER message specified in 3GPP TS 23.040.
Public Members
-
struct sms_address
originating_address
¶ Originating address, i.e., phone number.
-
struct sms_udh_app_port
app_port
¶ Application port addressing information.
-
struct sms_udh_concat
concatenated
¶ Concatenated short message information.
-
struct sms_address
-
union
sms_header
¶ - #include <sms.h>
SMS header.
This can easily be extended to support additional message types.
Public Members
-
struct sms_deliver_header
deliver
¶
-
struct sms_deliver_header
-
struct
sms_data
¶ - #include <sms.h>
SMS PDU data.
Public Members
-
union sms_header
header
¶ SMS header.
-
int
payload_len
¶ Length of the payload buffer.
-
uint8_t
payload
[160 + 1]¶ SMS message payload.
Reserving enough bytes for maximum number of characters but the length of the received payload is in payload_len variable.
Generally the message is of text type in which case you can treat it as string. However, header may contain information that determines it for specific purpose, e.g., via application port information, in which case it should be treated as specified for that purpose.
-
union sms_header
-