CellularDevice.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_DEVICE_H_
00019 #define CELLULAR_DEVICE_H_
00020 
00021 #include "CellularTargets.h"
00022 #include "EventQueue.h"
00023 #include "nsapi_types.h"
00024 #include "PlatformMutex.h"
00025 
00026 class NetworkStack;
00027 
00028 namespace mbed {
00029 
00030 class CellularPower;
00031 class CellularSMS;
00032 class CellularSIM;
00033 class CellularInformation;
00034 class CellularNetwork;
00035 class FileHandle;
00036 
00037 /**
00038  *  Class CellularDevice
00039  *
00040  *  An abstract interface that defines opening and closing of cellular interfaces.
00041  *  Deleting/Closing of opened interfaces can be done only via this class.
00042  */
00043 class CellularDevice {
00044 public:
00045 
00046     /** Return singleton instance of CellularDevice if CELLULAR_DEVICE is defined. If CELLULAR_DEVICE is not
00047      *  defined then returns NULL. Implementation is marked as weak.
00048      *
00049      *  @return CellularDevice* instance if any
00050      */
00051     static CellularDevice *get_default_instance();
00052 
00053     /** Get event queue that can be chained to main event queue. EventQueue is created in get_default_instance() or
00054      *  given to CELLULAR_DEVICE (for example TELIT_HE910 class).
00055      *  @return event queue
00056      */
00057     virtual events::EventQueue *get_queue() const;
00058 
00059     /** Default constructor
00060      */
00061     CellularDevice();
00062 
00063     /** virtual Destructor
00064      */
00065     virtual ~CellularDevice() {}
00066 
00067 public:
00068     /** Create new CellularNetwork interface.
00069      *
00070      *  @param fh    file handle used in communication to modem. Can be for example UART handle.
00071      *  @return      New instance of interface CellularNetwork.
00072      */
00073     virtual CellularNetwork *open_network(FileHandle *fh) = 0;
00074 
00075     /** Create new CellularSMS interface.
00076      *
00077      *  @param fh    file handle used in communication to modem. Can be for example UART handle.
00078      *  @return      New instance of interface CellularSMS.
00079      */
00080     virtual CellularSMS *open_sms(FileHandle *fh) = 0;
00081 
00082     /** Create new CellularPower interface.
00083      *
00084      *  @param fh    file handle used in communication to modem. Can be for example UART handle.
00085      *  @return      New instance of interface CellularPower.
00086      */
00087     virtual CellularPower *open_power(FileHandle *fh) = 0;
00088 
00089     /** Create new CellularSIM interface.
00090      *
00091      *  @param fh    file handle used in communication to modem. Can be for example UART handle.
00092      *  @return      New instance of interface CellularSIM.
00093      */
00094     virtual CellularSIM *open_sim(FileHandle *fh) = 0;
00095 
00096     /** Create new CellularInformation interface.
00097      *
00098      *  @param fh    file handle used in communication to modem. Can be for example UART handle.
00099      *  @return      New instance of interface CellularInformation.
00100      */
00101     virtual CellularInformation *open_information(FileHandle *fh) = 0;
00102 
00103     /** Closes the opened CellularNetwork by deleting the CellularNetwork instance.
00104      */
00105     virtual void close_network() = 0;
00106 
00107     /** Closes the opened CellularSMS by deleting the CellularSMS instance.
00108      */
00109     virtual void close_sms() = 0;
00110 
00111     /** Closes the opened CellularPower by deleting the CellularPower instance.
00112      */
00113     virtual void close_power() = 0;
00114 
00115     /** Closes the opened CellularSIM by deleting the CellularSIM instance.
00116      */
00117     virtual void close_sim() = 0;
00118 
00119     /** Closes the opened CellularInformation by deleting the CellularInformation instance.
00120      */
00121     virtual void close_information() = 0;
00122 
00123     /** Set the default response timeout.
00124      *
00125      *  @param timeout    milliseconds to wait response from modem
00126      */
00127     virtual void set_timeout(int timeout) = 0;
00128 
00129     /** Turn modem debug traces on
00130      *
00131      *  @param on         set true to enable debug traces
00132      */
00133     virtual void modem_debug_on(bool on) = 0;
00134 
00135     /** Get network stack.
00136      *
00137      *  @return network stack
00138      */
00139     virtual NetworkStack *get_stack() = 0;
00140 
00141     /** Initialize cellular module must be called right after module is ready.
00142      *  For example, when multiple modules are supported in a single AT driver this function detects
00143      *  and adapts to an actual module at runtime.
00144      *
00145      *  @param fh    file handle used in communication to modem.
00146      *
00147      *  @return 0 on success
00148      */
00149     virtual nsapi_error_t init_module(FileHandle *fh) = 0;
00150 
00151 protected:
00152     int _network_ref_count;
00153     int _sms_ref_count;
00154     int _power_ref_count;
00155     int _sim_ref_count;
00156     int _info_ref_count;
00157 };
00158 
00159 } // namespace mbed
00160 
00161 #endif // CELLULAR_DEVICE_H_