diff --git a/features/cellular/framework/API/CellularInformation.h b/features/cellular/framework/API/CellularInformation.h index 63cc24f9e9..19016cbac8 100644 --- a/features/cellular/framework/API/CellularInformation.h +++ b/features/cellular/framework/API/CellularInformation.h @@ -42,7 +42,8 @@ public: * * @param buf manufacturer identification as zero terminated string * @param buf_size max length of manufacturer identification is 2048 characters - * @return zero on success, on failure negative error code + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_manufacturer(char *buf, size_t buf_size) = 0; @@ -50,7 +51,8 @@ public: * * @param buf model identification as zero terminated string * @param buf_size max length of model identification is 2048 characters - * @return zero on success, on failure negative error code + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_model(char *buf, size_t buf_size) = 0; @@ -58,7 +60,8 @@ public: * * @param buf revision identification as zero terminated string * @param buf_size max length of revision identification is 2048 characters - * @return zero on success, on failure negative error code + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_revision(char *buf, size_t buf_size) = 0; @@ -67,7 +70,9 @@ public: * @param buf serial number as zero terminated string * @param buf_size max length of serial number is 2048 characters * @param type serial number type to read - * @return zero on success, on failure negative error code + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_UNSUPPORTED if SerialNumberType is not supported by the modem + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ enum SerialNumberType { SN = 0, // Serial Number diff --git a/features/cellular/framework/API/CellularNetwork.h b/features/cellular/framework/API/CellularNetwork.h index d4d4f3fe2a..2faccbe148 100644 --- a/features/cellular/framework/API/CellularNetwork.h +++ b/features/cellular/framework/API/CellularNetwork.h @@ -226,21 +226,24 @@ public: /** Does all the needed initializations that can fail * * @remark must be called immediately after constructor. - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_MEMORY on case of memory failure */ virtual nsapi_error_t init() = 0; /** Request registering to network. * * @param plmn format is in numeric format or 0 for automatic network registration - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_registration(const char *plmn = 0) = 0; /** Get the current network registering mode * - * @param mode on successful return contains the current network registering mode - * @return zero on success + * @param mode on successful return contains the current network registering mode + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_network_registering_mode(NWRegisteringMode &mode) = 0; @@ -249,17 +252,21 @@ public: * After successful call network class starts to get information about network changes like * registration statue, access technology, cell id... * - * @param type RegistrationType to set urc on/off - * @param on Controls are urc' active or not - * @return zero on success + * @param type RegistrationType to set urc on/off + * @param on Controls are urc' active or not + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_UNSUPPORTED if RegistrationType not supported by the modem + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_registration_urc(RegistrationType type, bool on) = 0; /** Gets the network registration status. * - * @param type see RegistrationType values - * @param status see RegistrationStatus values - * @return zero on success + * @param type see RegistrationType values + * @param status see RegistrationStatus values + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_UNSUPPORTED if RegistrationType not supported by the modem + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_registration_status(RegistrationType type, RegistrationStatus &status) = 0; @@ -268,7 +275,8 @@ public: * @param apn Optional name of the network to connect to * @param username Optional username for the APN * @param password Optional password fot the APN - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_MEMORY on case of memory failure */ virtual nsapi_error_t set_credentials(const char *apn, const char *username = 0, const char *password = 0) = 0; @@ -279,7 +287,8 @@ public: * @param type Authentication type to use * @param username Optional username for the APN * @param password Optional password fot the APN - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_MEMORY on case of memory failure */ virtual nsapi_error_t set_credentials(const char *apn, AuthenticationType type, const char *username = 0, const char *password = 0) = 0; @@ -287,22 +296,25 @@ public: /** Request attach to network. * * @deprecated Parameter timeout will be deprecated. Use mbed-os/features/cellular/framework/API/CellularDevice.h set_timeout instead. - * @param timeout milliseconds to wait for attach response - * @return zero on success + * @param timeout milliseconds to wait for attach response + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ MBED_DEPRECATED_SINCE("mbed-os-5.9", "Parameter timeout will be deprecated. Use mbed-os/features/cellular/framework/API/CellularDevice.h set_timeout instead.") virtual nsapi_error_t set_attach(int timeout = 10 * 1000) = 0; /** Request attach status from network. * - * @param status see AttachStatus values - * @return zero on success + * @param status see AttachStatus values + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_attach(AttachStatus &status) = 0; /** Request detach from a network. * - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t detach() = 0; @@ -312,7 +324,8 @@ public: * @param reports Additional exception reports at maximum rate reached are allowed to be sent [optional] * @param time_unit Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional] * @param uplink_rate Maximum number of messages per timeUnit [optional] - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_rate_control(CellularNetwork::RateControlExceptionReports &reports, CellularNetwork::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0; @@ -320,29 +333,36 @@ public: /** Get backoff timer value * * @param backoff_timer Backoff timer value associated with PDP APN in seconds - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_PARAMETER if no access point is set or found when activating context + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0; /** Sets radio access technology. * - * @param rat Radio access technology - * @return zero on success + * @param rat Radio access technology + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_UNSUPPORTED if the given opAct is RAT_UNKNOWN, inhering target class + * has not implemented method set_access_technology_impl(...) or returns NSAPI_ERROR_UNSUPPORTED + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_access_technology(RadioAccessTechnology rat) = 0; /** Get current radio access technology. * - * @param rat Radio access technology - * @return zero on success + * @param rat Radio access technology + * @return NSAPI_ERROR_OK */ virtual nsapi_error_t get_access_technology(RadioAccessTechnology &rat) = 0; /** Scans for operators module can reach. * - * @param operators Container of reachable operators and their access technologies - * @param ops_count Number of found operators - * @return zero on success + * @param operators Container of reachable operators and their access technologies + * @param ops_count Number of found operators + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_MEMORY on case of memory failure + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count) = 0; @@ -350,7 +370,8 @@ public: * * @param supported_opt Supported CIoT EPS optimizations. * @param preferred_opt Preferred CIoT EPS optimizations. - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_ciot_optimization_config(Supported_UE_Opt supported_opt, Preferred_UE_Opt preferred_opt) = 0; @@ -359,14 +380,20 @@ public: * * @param supported_opt Supported CIoT EPS optimizations. * @param preferred_opt Preferred CIoT EPS optimizations. - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_ciot_optimization_config(Supported_UE_Opt &supported_opt, Preferred_UE_Opt &preferred_opt) = 0; /** Start the interface. Attempts to connect to a cellular network. * - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_CONNECTION if fails to find suitable context to activate or activation failed (if not already activated) + * NSAPI_ERROR_UNSUPPORTED if NetworkStack was not found + * NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed + * Also if PPP mode + * NSAPI_ERROR_DEVICE_ERROR on case of failure and check more error from nsapi_ppp_connect(...) */ virtual nsapi_error_t connect() = 0; @@ -375,7 +402,13 @@ public: * @param apn Optional name of the network to connect to * @param username Optional username for your APN * @param password Optional password for your APN - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_CONNECTION if fails to find suitable context to activate or activation failed (if not already activated) + * NSAPI_ERROR_UNSUPPORTED if NetworkStack was not found + * NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed + * NSAPI_ERROR_NO_MEMORY on case of memory failure + * Also if PPP mode + * NSAPI_ERROR_DEVICE_ERROR on case of failure and check more error from nsapi_ppp_connect(...) */ virtual nsapi_error_t connect(const char *apn, const char *username = 0, const char *password = 0) = 0; @@ -383,7 +416,10 @@ public: /** Finds the correct PDP context and activates it. If correct PDP context is not found, one is created. * Given APN (or not given) and stack type (IPv4/IPv6/dual) are influencing when finding the PDP context. * - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_CONNECTION if fails to find suitable context to activate or activation failed (if not already activated) + * NSAPI_ERROR_UNSUPPORTED if NetworkStack was not found + * NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed */ virtual nsapi_error_t activate_context() = 0; @@ -392,7 +428,8 @@ public: * * @param stack_type the stack type to be used. * - * @return NSAPI_ERROR_OK on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_PARAMETER if modem don't support the given stack_type */ virtual nsapi_error_t set_stack_type(nsapi_ip_stack_t stack_type) = 0; @@ -406,35 +443,39 @@ public: /** Get the relevant information for an active non secondary PDP context. * * @remark optional params are not updated if not received from network. - * @param params_list reference to linked list which is filled on successful call - * @return 0 on success, negative error code on failure + * @param params_list reference to linked list which is filled on successful call + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_MEMORY on case of memory failure + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t ¶ms_list) = 0; /** Get extended signal quality parameters. * - * @param rxlev signal strength level - * @param ber bit error rate - * @param rscp signal code power - * @param ecno ratio of the received energy per PN chip to the total received power spectral density - * @param rsrq signal received quality - * @param rsrp signal received power - * @return NSAPI_ERROR_OK on success, negative error code on failure + * @param rxlev signal strength level + * @param ber bit error rate + * @param rscp signal code power + * @param ecno ratio of the received energy per PN chip to the total received power spectral density + * @param rsrq signal received quality + * @param rsrp signal received power + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_error_t get_extended_signal_quality(int &rxlev, int &ber, int &rscp, int &ecno, int &rsrq, int &rsrp) = 0; /** Get signal quality parameters. * - * @param rssi signal strength level - * @param ber bit error rate - * @return NSAPI_ERROR_OK on success, negative error code on failure + * @param rssi signal strength level + * @param ber bit error rate + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_error_t get_signal_quality(int &rssi, int &ber) = 0; /** Get cell id. * - * @param cell_id cell id - * @return NSAPI_ERROR_OK on success, negative error code on failure + * @param cell_id cell id + * @return NSAPI_ERROR_OK */ virtual nsapi_error_t get_cell_id(int &cell_id) = 0; @@ -445,9 +486,10 @@ public: /** Get the operator parameters. * - * @param format format of the operator field - * @param operator_params applicable operator param fields filled - * @return NSAPI_ERROR_OK on success, negative error code on failure + * @param format format of the operator field + * @param operator_params applicable operator param fields filled + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params) = 0; @@ -470,14 +512,17 @@ public: /** Set blocking status of connect() which by default should be blocking * * @param blocking true if connect is blocking - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK + * if PPP mode check errors from nsapi_ppp_set_blocking(...) */ virtual nsapi_error_t set_blocking(bool blocking) = 0; /** Read operator names * - * @param op_names on successful return will contain linked list of operator names. - * @return zero on success + * @param op_names on successful return will contain linked list of operator names. + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_MEMORY on case of memory failure + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_error_t get_operator_names(operator_names_list &op_names) = 0; }; diff --git a/features/cellular/framework/API/CellularPower.h b/features/cellular/framework/API/CellularPower.h index a2ecdf7373..0530498968 100644 --- a/features/cellular/framework/API/CellularPower.h +++ b/features/cellular/framework/API/CellularPower.h @@ -53,7 +53,8 @@ public: * * @remark set_at_mode must be called to initialise modem * - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_UNSUPPORTED if not overridden by the target modem */ virtual nsapi_error_t on() = 0; @@ -61,8 +62,8 @@ public: * Device power on/off is modem/board specific behavior and must be done on inherited class if needed. * Power off is done by toggling power pin/button. * - * - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_UNSUPPORTED if not overridden by the target modem */ virtual nsapi_error_t off() = 0; @@ -70,7 +71,8 @@ public: * * @remark must be called after power on to prepare correct AT mode * - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_at_mode() = 0; @@ -88,13 +90,15 @@ public: * * @remark See 3GPP TS 27.007 CFUN for more details * - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_power_level(int func_level, int do_reset = 0) = 0; /** Reset and wake-up cellular device. * - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t reset() = 0; @@ -104,7 +108,9 @@ public: * * @param periodic_time Timeout in seconds IoT subsystem is not expecting messaging * @param active_time Timeout in seconds IoT subsystem waits for response - * @return zero on success + * + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t opt_power_save_mode(int periodic_time, int active_time) = 0; @@ -116,13 +122,15 @@ public: * @param act_type type of access technology * @param edrx_value requested edxr value. Extended DRX parameters information element. * - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t opt_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value) = 0; /** Check whether the device is ready to accept commands. * - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t is_device_ready() = 0; @@ -131,7 +139,10 @@ public: * for using at commands and possible sim. * * @param callback Callback function called when urc received - * @return zero on success + * + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_MEMORY on case of memory failure + * NSAPI_ERROR_UNSUPPORTED if not overridden by the target modem */ virtual nsapi_error_t set_device_ready_urc_cb(mbed::Callback callback) = 0; diff --git a/features/cellular/framework/API/CellularSIM.h b/features/cellular/framework/API/CellularSIM.h index 238782fba6..566f8efd34 100644 --- a/features/cellular/framework/API/CellularSIM.h +++ b/features/cellular/framework/API/CellularSIM.h @@ -54,7 +54,8 @@ public: /** Open the SIM card by setting the pin code for SIM. * * @param sim_pin PIN for the SIM card - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_pin(const char *sim_pin) = 0; @@ -62,7 +63,8 @@ public: * * @param sim_pin Current PIN for sim * @param new_pin New PIN for sim - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t change_pin(const char *sim_pin, const char *new_pin) = 0; @@ -70,14 +72,16 @@ public: * * @param sim_pin Valid PIN for SIM card * @param query_pin False is PIN query not needed, True if PIN query needed after boot. - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_pin_query(const char *sim_pin, bool query_pin) = 0; /** Get sim card's state * * @param state current state of SIM - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_sim_state(SimState &state) = 0; @@ -85,7 +89,9 @@ public: * @remark Given imsi buffer length must be 16 or more as imsi max length is 15! * * @param imsi preallocated char* which after successful request contains imsi - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_PARAMETER if imsi if null + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_error_t get_imsi(char *imsi) = 0; @@ -93,7 +99,8 @@ public: * * @param buf SIM ICCID as zero terminated string * @param buf_size max length of SIM ICCID is MAX_ICCID_LENGTH - * @return zero on success, on failure negative error code + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t get_iccid(char *buf, size_t buf_size) = 0; }; diff --git a/features/cellular/framework/API/CellularSMS.h b/features/cellular/framework/API/CellularSMS.h index 3ea5b2c267..29ed5aede6 100644 --- a/features/cellular/framework/API/CellularSMS.h +++ b/features/cellular/framework/API/CellularSMS.h @@ -60,7 +60,9 @@ public: /** Does all the necessary initializations needed for receiving and sending sms. * * @param mode enumeration for choosing the correct mode: text/pdu - * @return zero on success + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_NO_MEMORY on case of memory failure + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_error_t initialize(CellularSMSMmode mode) = 0; @@ -69,7 +71,10 @@ public: * @param phone_number Phone number where to send sms * @param message SMS message content * @param msg_len Length of the message - * @return possible error code or length of the sent sms + * @return On success, length of the sent sms (positive value) + * NSAPI_ERROR_PARAMETER if invalid parameters + * NSAPI_ERROR_NO_MEMORY on case of memory failure + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_size_or_error_t send_sms(const char *phone_number, const char *message, int msg_len) = 0; @@ -84,8 +89,12 @@ public: * @param time_len length of allocated time_stamp buffer * @param buf_size if method return error NSAPI_ERROR_NO_MEMORY because the given buf was not big enough this will * hold the size which is enough. Otherwise zero. - * @return possible error code or size of buf. Will return SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ - * if sms was multipart but not all parts are present/failed to read. + * @return On success, length of the received sms, (length of the buf, positive value) + * NSAPI_ERROR_PARAMETER if invalid parameters + * NSAPI_ERROR_NO_MEMORY on case of memory failure + * SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ if sms was multipart but not all parts are present/failed to read. + * -1 if no sms was found + * NSAPI_ERROR_DEVICE_ERROR on case of other failures */ virtual nsapi_size_or_error_t get_sms(char *buf, uint16_t buf_len, char *phone_num, uint16_t phone_len, char *time_stamp, uint16_t time_len, int *buf_size) = 0; @@ -110,7 +119,8 @@ public: * "SM" - SIM SMS memory storage (default) * "ME" - NVM SMS storage * - * @return 1 for success, 0 for failure + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_cpms(const char *memr, const char *memw, const char *mems) = 0; @@ -119,7 +129,8 @@ public: * @param sca Service Center Address to be used for mobile originated SMS transmissions. * @param type 129 - national numbering scheme, 145 - international numbering scheme (contains the character "+") * - * @return 1 for success, 0 for failure + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t set_csca(const char *sca, int type) = 0; @@ -130,13 +141,15 @@ public: * @param chr_set preferred character set list (comma separated). Modem might not support the wanted character set * so chr_set list is looped from start until supported set is found. Used character set index is returned. * See more from 3GPP TS 27.005. - * @return Used character set index from the given list in case of success. Otherwise negative errorcode. + * @return Used character set index from the given list in case of success. + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_size_or_error_t set_cscs(const char *chr_set) = 0; /** Deletes all messages from the currently set memory/SIM * - * @return possible error code + * @return NSAPI_ERROR_OK on success + * NSAPI_ERROR_DEVICE_ERROR on case of failure */ virtual nsapi_error_t delete_all_messages() = 0;