Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
CellularSMS.h
1 /*
2  * Copyright (c) 2017, Arm Limited and affiliates.
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef CELLULAR_SMS_H_
19 #define CELLULAR_SMS_H_
20 
21 #if MBED_CONF_CELLULAR_USE_SMS
22 
23 #include "Callback.h"
24 #include "netsocket/nsapi_types.h"
25 
26 namespace mbed {
27 
28 // including trailing '\0'
29 const uint16_t SMS_MAX_SIZE_WITH_CONCATENATION = 4096 + 1;
30 const uint16_t SMS_MAX_PHONE_NUMBER_SIZE = 20 + 1;
31 const uint16_t SMS_MAX_TIME_STAMP_SIZE = 20 + 1;
32 
33 const uint16_t SMS_MAX_SIZE_8BIT_SINGLE_SMS_SIZE = 140;
34 const uint16_t SMS_MAX_SIZE_GSM7_SINGLE_SMS_SIZE = 160;
35 
36 const uint16_t SMS_SIM_WAIT_TIME_MILLISECONDS = 200;
37 
38 const int SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ = -5001;
39 
40 /**
41  * @addtogroup cellular
42  * @{
43  */
44 
45 /**
46  * Class CellularSMS
47  *
48  * An abstract interface for SMS sending, reading and deleting.
49  */
50 class CellularSMS {
51 protected:
52  // friend of CellularDevice so that it's the only way to close/delete this class.
53  friend class CellularDevice;
54 
55  /**
56  * virtual Destructor
57  */
58  virtual ~CellularSMS() {};
59 
60 public:
61  /* Enumeration for possible SMS modes, PDU and Text */
62  enum CellularSMSMmode {
63  CellularSMSMmodePDU = 0,
64  CellularSMSMmodeText
65  };
66 
67  enum CellularSMSEncoding {
68  CellularSMSEncoding7Bit,
69  CellularSMSEncoding8Bit,
70  };
71 
72  /** Does all the necessary initializations needed for receiving and sending SMS.
73  *
74  * @param mode enumeration for choosing the correct mode: text/pdu
75  * @return NSAPI_ERROR_OK on success
76  * NSAPI_ERROR_NO_MEMORY on memory failure
77  * NSAPI_ERROR_DEVICE_ERROR on other failures
78  */
79  virtual nsapi_error_t initialize(CellularSMSMmode mode,
80  CellularSMSEncoding encoding = CellularSMSEncoding::CellularSMSEncoding7Bit) = 0;
81 
82  /** Send the SMS with the given parameters
83  *
84  * @param phone_number Phone number where to send SMS
85  * @param message SMS message content
86  * @param msg_len Length of the message
87  * @return On success, length of the sent SMS (positive value)
88  * NSAPI_ERROR_PARAMETER if invalid parameters
89  * NSAPI_ERROR_NO_MEMORY on memory failure
90  * NSAPI_ERROR_DEVICE_ERROR on other failures
91  */
92  virtual nsapi_size_or_error_t send_sms(const char *phone_number, const char *message, int msg_len) = 0;
93 
94  /** Gets the oldest received sms.
95  *
96  * @param buf preallocated buffer for SMS message content
97  * @param buf_len length of allocated buf
98  * @param phone_num preallocated buffer for phone number where SMS was sent
99  * @param phone_len length of allocated phone_num buffer
100  * @param time_stamp preallocated buffer for TP-Service Centre Time Stamp (format: yy/MM/dd,hh:mm:ss-+zz). +-zz is timezone.
101  * The unit of time zone is a quarter of an hour relative to GMT. For example +32 would be GMT+8.
102  * @param time_len length of allocated time_stamp buffer
103  * @param buf_size if method return error NSAPI_ERROR_NO_MEMORY because the given buf was not big enough, this
104  * holds the size which is enough. Otherwise zero.
105  * @return On success, length of the received SMS, (length of the buf, positive value)
106  * NSAPI_ERROR_PARAMETER if invalid parameters
107  * NSAPI_ERROR_NO_MEMORY on memory failure
108  * SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ if SMS was multipart but not all parts are present/failed to read.
109  * -1 if no SMS was found
110  * NSAPI_ERROR_DEVICE_ERROR on other failures
111  */
112  virtual nsapi_size_or_error_t get_sms(char *buf, uint16_t buf_len, char *phone_num, uint16_t phone_len,
113  char *time_stamp, uint16_t time_len, int *buf_size) = 0;
114 
115  /** Callback that is called when new SMS is received. SMS can be fetched using method get_sms().
116  *
117  * @remark In PDU mode, there can be multipart SMS, and callback is called for every received part.
118  *
119  * @param func Callback function that is called when new SMS is received.
120  */
121  virtual void set_sms_callback(Callback<void()> func) = 0;
122 
123  /** CPMS preferred message storage
124  *
125  * @param memr memory from which messages are read and deleted
126  * "SM" - SIM SMS memory storage (default)
127  * "ME" - NVM SMS storage
128  * @param memw memory to which writing and sending operations are made
129  * "SM" - SIM SMS memory storage (default)
130  * "ME" - NVM SMS storage
131  * @param mems memory to which received SMs are preferred to be stored
132  * "SM" - SIM SMS memory storage (default)
133  * "ME" - NVM SMS storage
134  *
135  * @return NSAPI_ERROR_OK on success
136  * NSAPI_ERROR_DEVICE_ERROR on failure
137  */
138  virtual nsapi_error_t set_cpms(const char *memr, const char *memw, const char *mems) = 0;
139 
140  /** CSCA - set Service Center Address
141  *
142  * @param sca Service Center Address to be used for mobile originated SMS transmissions.
143  * @param type 129 - national numbering scheme, 145 - international numbering scheme (contains the character "+")
144  *
145  * @return NSAPI_ERROR_OK on success
146  * NSAPI_ERROR_DEVICE_ERROR on failure
147  */
148  virtual nsapi_error_t set_csca(const char *sca, int type) = 0;
149 
150  /** Set command sets the current character set used by the device. "GSM", "IRA",....
151  *
152  * @remark Current implementation support only ASCII so choose the correct character set.
153  *
154  * @param chr_set preferred character set list (comma separated). Modem might not support the wanted character set,
155  * so chr_set list is looped from start until supported set is found. Used character set index is returned.
156  * See more from 3GPP TS 27.005.
157  * @return Used character set index from the given list in case of success.
158  * NSAPI_ERROR_DEVICE_ERROR on failure
159  */
160  virtual nsapi_size_or_error_t set_cscs(const char *chr_set) = 0;
161 
162  /** Deletes all messages from the currently set memory/SIM
163  *
164  * @return NSAPI_ERROR_OK on success
165  * NSAPI_ERROR_DEVICE_ERROR on failure
166  */
167  virtual nsapi_error_t delete_all_messages() = 0;
168 
169  /** Some modems need extra time between AT commands and responses, or there will be error -314, SIM busy.
170  * If SIM busy errors are an issue, this time should be increased. It can also be set to zero to make
171  * operations faster and more energy efficient if no errors will follow. By default, wait time is zero.
172  *
173  * @param sim_wait_time
174  */
175  virtual void set_extra_sim_wait_time(int sim_wait_time) = 0;
176 };
177 
178 /**
179  * @}
180  */
181 
182 } // namespace mbed
183 
184 #endif // MBED_CONF_CELLULAR_USE_SMS
185 
186 #endif // CELLULAR_SMS_H_
nsapi_error_t
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:140
nsapi_size_or_error_t
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:151
mbed
Definition: ATHandler.h:46
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.