CellularSMS.h

00001 /*
00002  * Copyright (c) 2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef CELLULAR_SMS_H_
00019 #define CELLULAR_SMS_H_
00020 
00021 #include "Callback.h"
00022 #include "nsapi_types.h"
00023 
00024 namespace mbed {
00025 
00026 // including trailing '\0'
00027 const uint16_t SMS_MAX_SIZE_WITH_CONCATENATION = 4096 + 1;
00028 const uint16_t SMS_MAX_PHONE_NUMBER_SIZE = 20 + 1;
00029 const uint16_t SMS_MAX_TIME_STAMP_SIZE = 20 + 1;
00030 
00031 const uint16_t SMS_MAX_SIZE_8BIT_SINGLE_SMS_SIZE = 140;
00032 const uint16_t SMS_MAX_SIZE_GSM7_SINGLE_SMS_SIZE = 160;
00033 
00034 const uint16_t SMS_SIM_WAIT_TIME_MILLISECONDS = 200;
00035 
00036 const int SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ = -5001;
00037 
00038 /**
00039  *  Class CellularSMS
00040  *
00041  *  An abstract interface for SMS sending, reading and deleting.
00042  */
00043 class CellularSMS
00044 {
00045 protected:
00046     // friend of CellularDevice so that it's the only way to close/delete this class.
00047     friend class CellularDevice;
00048 
00049     /**
00050      * virtual Destructor
00051      */
00052     virtual ~CellularSMS() {};
00053 public:
00054 
00055     /* Enumeration for possible SMS modes, PDU and Text */
00056     enum CellularSMSMmode {
00057         CellularSMSMmodePDU = 0,
00058         CellularSMSMmodeText
00059     };
00060 
00061     /** Does all the necessary initializations needed for receiving and sending sms.
00062      *
00063      *  @param mode          enumeration for choosing the correct mode: text/pdu
00064      *  @return              zero on success
00065      */
00066     virtual nsapi_error_t initialize(CellularSMSMmode mode) = 0;
00067 
00068     /** Send the SMS with the given parameters
00069      *
00070      *  @param phone_number  Phone number where to send sms
00071      *  @param message       SMS message content
00072      *  @param msg_len       Length of the message
00073      *  @return              possible error code or length of the sent sms
00074      */
00075     virtual nsapi_size_or_error_t send_sms(const char* phone_number, const char* message, int msg_len) = 0;
00076 
00077     /** Gets the oldest received sms.
00078      *
00079      *  @param buf           preallocated buffer for sms message content
00080      *  @param buf_len       length of allocated buf
00081      *  @param phone_num     preallocated buffer for phone number where sms was sent
00082      *  @param phone_len     length of allocated phone_num  buffer
00083      *  @param time_stamp    preallocated buffer for TP-Service Centre Time Stamp (format: yy/MM/dd,hh:mm:ss-+zz). +-zz is timezone.
00084      *                       The unit of time zone is a quarter of an hour relative to GMT. For example +32 would be GMT+8.
00085      *  @param time_len      length of allocated time_stamp buffer
00086      *  @param buf_size      if method return error NSAPI_ERROR_NO_MEMORY because the given buf was not big enough this will
00087      *                       hold the size which is enough. Otherwise zero.
00088      *  @return              possible error code or size of buf. Will return SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ
00089      *                       if sms was multipart but not all parts are present/failed to read.
00090      */
00091     virtual nsapi_size_or_error_t get_sms(char* buf, uint16_t buf_len, char* phone_num, uint16_t phone_len,
00092             char* time_stamp, uint16_t time_len, int *buf_size) = 0;
00093 
00094     /** Callback which is called when new sms is received. SMS can be fetched via method get_sms().
00095      *
00096      * @remark      In PDU mode there can be multipart sms and callback is called for every received part.
00097      *
00098      * @param func  Callback function which is called when new sms is received.
00099      */
00100     virtual void set_sms_callback(Callback<void()> func) = 0;
00101 
00102     /** CPMS preferred message storage
00103      *
00104      *  @param memr        memory from which messages are read and deleted
00105      *                     "SM" - SIM SMS memory storage (default)
00106      *                     "ME" - NVM SMS storage
00107      *  @param memw        memory to which writing and sending operations are made
00108      *                     "SM" - SIM SMS memory storage (default)
00109      *                     "ME" - NVM SMS storage
00110      *  @param mems        memory to which received SMs are preferred to be stored
00111      *                     "SM" - SIM SMS memory storage (default)
00112      *                     "ME" - NVM SMS storage
00113      *
00114      * @return             1 for success, 0 for failure
00115      */
00116     virtual nsapi_error_t set_cpms(const char *memr, const char *memw, const char *mems) = 0;
00117 
00118     /** CSCA - set Service Center Address
00119      *
00120      *  @param sca        Service Center Address to be used for mobile originated SMS transmissions.
00121      *  @param type       129 - national numbering scheme, 145 - international numbering scheme (contains the character "+")
00122      *
00123      *  @return           1 for success, 0 for failure
00124      */
00125     virtual nsapi_error_t set_csca(const char *sca, int type) = 0;
00126 
00127     /** Set command sets the current character set used by the device. "GSM", "IRA",....
00128      *
00129      *  @remark Current implementation support only ASCII so choose the correct character set.
00130      *
00131      *  @param chr_set   preferred character set list (comma separated). Modem might not support the wanted character set
00132      *                   so chr_set list is looped from start until supported set is found. Used character set index is returned.
00133      *                   See more from 3GPP TS 27.005.
00134      * @return           Used character set index from the given list in case of success. Otherwise negative errorcode.
00135      */
00136     virtual nsapi_size_or_error_t set_cscs(const char *chr_set) = 0;
00137 
00138     /** Deletes all messages from the currently set memory/SIM
00139      *
00140      *  @return possible error code
00141      */
00142     virtual nsapi_error_t delete_all_messages() = 0;
00143 
00144     /** Some modems need extra time between AT commands and responses or there will be error -314, SIM busy.
00145      *  If SIM busy errors are an issue this time should be increased. It can also be set to zero to make
00146      *  operations faster and more energy efficient if no errors will follow. By default wait time is zero.
00147      *
00148      *  @param sim_wait_time
00149      */
00150     virtual void set_extra_sim_wait_time(int sim_wait_time) = 0;
00151 };
00152 
00153 } // namespace mbed
00154 
00155 #endif // CELLULAR_SMS_H_