CellularSIM.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_SIM_H_
00019 #define CELLULAR_SIM_H_
00020 
00021 #include <stddef.h>
00022 
00023 #include "nsapi_types.h"
00024 
00025 namespace mbed {
00026 
00027 const int MAX_SIM_READY_WAITING_TIME = 30;
00028 const int MAX_IMSI_LENGTH = 15;
00029 const int MAX_ICCID_LENGTH = 20 + 1; // +1 for zero termination
00030 /**
00031  *  Class CellularSIM
00032  *
00033  *  An abstract interface for SIM card handling.
00034  */
00035 class CellularSIM {
00036 protected:
00037     // friend of CellularDevice so that it's the only way to close/delete this class.
00038     friend class CellularDevice;
00039 
00040     /**
00041      * virtual Destructor
00042      */
00043     virtual ~CellularSIM() {};
00044 
00045 public:
00046     /* enumeration for possible SIM states */
00047     enum SimState {
00048         SimStateReady = 0,
00049         SimStatePinNeeded,
00050         SimStatePukNeeded,
00051         SimStateUnknown
00052     };
00053 
00054     /** Open the SIM card by setting the pin code for SIM.
00055      *
00056      *  @param sim_pin  PIN for the SIM card
00057      *  @return         NSAPI_ERROR_OK on success
00058      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00059      */
00060     virtual nsapi_error_t set_pin(const char *sim_pin) = 0;
00061 
00062     /** Change SIM pin code.
00063      *
00064      *  @param sim_pin  Current PIN for SIM
00065      *  @param new_pin  New PIN for SIM
00066      *  @return         NSAPI_ERROR_OK on success
00067      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00068      */
00069     virtual nsapi_error_t change_pin(const char *sim_pin, const char *new_pin) = 0;
00070 
00071     /** Change is pin query needed after boot
00072      *
00073      *  @param sim_pin      Valid PIN for SIM card
00074      *  @param query_pin    False if PIN query not needed, True if PIN query needed after boot.
00075      *  @return         NSAPI_ERROR_OK on success
00076      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00077      */
00078     virtual nsapi_error_t set_pin_query(const char *sim_pin, bool query_pin) = 0;
00079 
00080     /** Get SIM card's state
00081      *
00082      *  @param state    current state of SIM
00083      *  @return         NSAPI_ERROR_OK on success
00084      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00085      */
00086     virtual nsapi_error_t get_sim_state(SimState &state) = 0;
00087 
00088     /** Get IMSI from the sim card
00089      *  @remark         Given imsi buffer length must be 16 or more as imsi max length is 15!
00090      *
00091      *  @param imsi     preallocated char* which after successful request contains imsi
00092      *  @return         NSAPI_ERROR_OK on success
00093      *                  NSAPI_ERROR_PARAMETER if imsi if null
00094      *                  NSAPI_ERROR_DEVICE_ERROR on other failures
00095      */
00096     virtual nsapi_error_t get_imsi(char *imsi) = 0;
00097 
00098     /** Get serial number from the SIM card
00099      *
00100      *  @param buf      SIM ICCID as zero terminated string
00101      *  @param buf_size max length of SIM ICCID is MAX_ICCID_LENGTH
00102      *  @return         NSAPI_ERROR_OK on success
00103      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00104      */
00105     virtual nsapi_error_t get_iccid(char *buf, size_t buf_size) = 0;
00106 };
00107 
00108 } // namespace mbed
00109 
00110 #endif // CELLULAR_SIM_H_