CellularNetwork Class Reference

Hostname translation callback (asynchronous)

Callback will be called after DNS resolution completes or a failure occurs.

Callback should not take more than 10ms to execute, otherwise it might prevent underlying thread processing. A portable user of the callback should not make calls to network operations due to stack size limitations. The callback should not perform expensive operations such as socket recv/send calls or blocking operations.

Parameters:

status	0 on success, negative error code on failure
address	On success, destination for the host SocketAddress

Definition at line 180 of file NetworkInterface.h.

virtual Destructor

Definition at line 46 of file CellularNetwork.h.

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.

Returns:

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

Implemented in AT_CellularNetwork.

Add a domain name server to list of servers to query.

Parameters:

address

Destination for the host address

Returns:

0 on success, negative error code on failure

Definition at line 73 of file NetworkInterface.cpp.

Register callback for status reporting.

The specified status callback function will be called on status changes on the network. The parameters on the callback are the event type and event-type dependent reason parameter.

Parameters:

status_cb

The callback for status changes

Dynamic downcast to a CellularBase.

Definition at line 265 of file NetworkInterface.h.

Start the interface.

Attempts to connect to a cellular network.

Returns:

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 or cellular device does not support authentication NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed Also if PPP mode NSAPI_ERROR_DEVICE_ERROR on failure and check more error from nsapi_ppp_connect(...)

Implemented in AT_CellularNetwork.

Start the interface.

Attempts to connect to a cellular network.

Parameters:

apn	Optional name of the network to connect to
username	Optional username for your APN
password	Optional password for your APN

Returns:

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 memory failure Also if PPP mode NSAPI_ERROR_DEVICE_ERROR on failure and check more error from nsapi_ppp_connect(...)

Implemented in AT_CellularNetwork.

Request detach from a network.

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularNetwork.

Stop the interface.

Returns:

0 on success, negative error code on failure

Dynamic downcast to an EMACInterface.

Definition at line 271 of file NetworkInterface.h.

Dynamic downcast to an EthInterface.

Definition at line 247 of file NetworkInterface.h.

Get the last 3GPP error code.

Returns:

see 3GPP TS 27.007 error codes

Implemented in AT_CellularNetwork.

Get current radio access technology.

Parameters:

rat	Radio access technology

Returns:

NSAPI_ERROR_OK

Implemented in AT_CellularNetwork.

Get backoff timer value.

Parameters:

backoff_timer

Backoff timer value associated with PDP APN in seconds

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_PARAMETER if no access point is set or found when activating context NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularNetwork.

Request attach status from network.

Parameters:

status

see AttachStatus values

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularNetwork.

Get cell id.

Parameters:

cell_id

cell ID

Returns:

NSAPI_ERROR_OK

Implemented in AT_CellularNetwork.

Get CIoT optimizations.

Parameters:

supported_opt	Supported CIoT EPS optimizations.
preferred_opt	Preferred CIoT EPS optimizations.

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularNetwork.

Get the connection status.

Returns:

The connection status according to ConnectionStatusType

Implemented in AT_CellularNetwork.

Return the default network interface.

Returns the default network interface, as determined by JSON option target.network-default-interface-type or other overrides.

The type of the interface returned can be tested via the ethInterface() etc downcasts.

The default behaviour is to return the default interface for the interface type specified by target.network-default-interface-type. Targets should set this in their targets.json to guide default selection, and applications may override.

The interface returned should be already configured for use such that its connect() method works with no parameters. For connection types needing configuration, settings should normally be obtained from JSON - the settings for the core types are under the "nsapi" JSON config tree.

The list of possible settings for default interface type is open-ended, as is the number of possible providers. Core providers are:

* ETHERNET: EthernetInterface, using default EMAC and OnboardNetworkStack * MESH: ThreadInterface or LoWPANNDInterface, using default NanostackRfPhy * CELLULAR: OnboardModemInterface * WIFI: None - always provided by a specific class

Specific drivers may be activated by other settings of the default-network-interface-type configuration. This will depend on the target and the driver. For example a board may have its default setting as "AUTO" which causes it to autodetect an Ethernet cable. This should be described in the target's documentation.

An application can override all target settings by implementing NetworkInterface::get_default_instance() themselves - the default definition is weak, and calls get_target_default_instance().

Definition at line 60 of file NetworkInterfaceDefaults.cpp.

Get extended signal quality parameters.

Parameters:

rxlev	signal strength level
ber	bit error rate
rscp	signal code power
ecno	ratio of the received energy per PN chip to the total received power spectral density
rsrq	signal received quality
rsrp	signal received power

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on other failures

Implemented in AT_CellularNetwork.

Get the local gateway.

Returns:

Null-terminated representation of the local gateway or null if no network mask has been received

Definition at line 38 of file NetworkInterface.cpp.

Get the local IP address.

Returns:

Null-terminated representation of the local IP address or null if no IP address has been received

Definition at line 28 of file NetworkInterface.cpp.

Get the local MAC address.

Provided MAC address is intended for info or debug purposes and may not be provided if the underlying network interface does not provide a MAC address

Returns:

Null-terminated representation of the local MAC address or null if no MAC address is available

Definition at line 23 of file NetworkInterface.cpp.

Get the local network mask.

Returns:

Null-terminated representation of the local network mask or null if no network mask has been received

Definition at line 33 of file NetworkInterface.cpp.

Get the current network registering mode.

Parameters:

mode	on successful return contains the current network registering mode

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularNetwork.

Read operator names.

Parameters:

op_names

on successful return contains linked list of operator names.

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on memory failure NSAPI_ERROR_DEVICE_ERROR on other failures

Implemented in AT_CellularNetwork.

Get the operator parameters.

Parameters:

format	format of the operator field
operator_params	applicable operator param fields filled

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on case of other failures

Implemented in AT_CellularNetwork.

Get the relevant information for an active non secondary PDP context.

Remarks:

optional params are not updated if not received from network.

Parameters:

params_list

reference to linked list, which is filled on successful call

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on memory failure NSAPI_ERROR_DEVICE_ERROR on other failures

Implemented in AT_CellularNetwork.

Get APN rate control.

Remarks:

optional params are not updated if not received from network, so use good defaults

Parameters:

reports	Additional exception reports at maximum rate reached are allowed to be sent [optional]
time_unit	Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional]
uplink_rate	Maximum number of messages per timeUnit [optional]

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on case of failure

Implemented in AT_CellularNetwork.

Gets the network registration status.

Parameters:

type	see RegistrationType values
status	see RegistrationStatus values

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularNetwork.

Get signal quality parameters.

Parameters:

rssi	signal strength level
ber	bit error rate

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on other failures

Implemented in AT_CellularNetwork.

Provide access to the NetworkStack object.

Returns:

The underlying NetworkStack object

Get the pdn type in use.

Returns:

stack type

Implemented in AT_CellularNetwork.

Get the target's default network instance.

This method can be overridden by the target. Default implementations are provided weakly by various subsystems as described in NetworkInterface::get_default_instance(), so targets should not need to override in simple cases.

If a target has more elaborate interface selection, it can completely override this behaviour by implementing NetworkInterface::get_target_default_instance() themselves, either unconditionally, or for a specific network-default-interface-type setting

For example, a device with both Ethernet and Wi-fi could be set up its target so that: * DEVICE_EMAC is set, and it provides EMAC::get_default_instance(), which means EthernetInterface provides EthInterface::get_target_instance() based on that EMAC. * It provides WifiInterface::get_target_default_instance(). * The core will route NetworkInterface::get_default_instance() to either of those if network-default-interface-type is set to ETHERNET or WIFI. * The board overrides NetworkInterface::get_target_default_instance() if network-default-interface-type is set to AUTO. This returns either EthInterface::get_default_instance() or WiFIInterface::get_default_instance() depending on a cable detection.

performs the search described by get_default_instance.

Definition at line 74 of file NetworkInterfaceDefaults.cpp.

Translates a hostname to an IP address with specific version.

The hostname may be either a domain name or an IP address. If the hostname is an IP address, no network transactions will be performed.

If no stack-specific DNS resolution is provided, the hostname will be resolve using a UDP socket on the stack.

Parameters:

host	Hostname to resolve
address	Destination for the host SocketAddress
version	IP version of address to resolve, NSAPI_UNSPEC indicates version is chosen by the stack (defaults to NSAPI_UNSPEC)

Returns:

0 on success, negative error code on failure

Definition at line 58 of file NetworkInterface.cpp.

Translates a hostname to an IP address (asynchronous)

The hostname may be either a domain name or an IP address. If the hostname is an IP address, no network transactions will be performed.

If no stack-specific DNS resolution is provided, the hostname will be resolve using a UDP socket on the stack.

Call is non-blocking. Result of the DNS operation is returned by the callback. If this function returns failure, callback will not be called. In case result is success (IP address was found from DNS cache), callback will be called before function returns.

Parameters:

host	Hostname to resolve
callback	Callback that is called for result
version	IP version of address to resolve, NSAPI_UNSPEC indicates version is chosen by the stack (defaults to NSAPI_UNSPEC)

Returns:

0 on immediate success, negative error code on immediate failure or a positive unique id that represents the hostname translation operation and can be passed to cancel

Definition at line 63 of file NetworkInterface.cpp.

Cancels asynchronous hostname translation.

When translation is cancelled, callback will not be called.

Parameters:

id	Unique id of the hostname translation operation

Returns:

0 on success, negative error code on failure

Definition at line 68 of file NetworkInterface.cpp.

Does all the needed initializations that can fail.

Remarks:

must be called immediately after constructor.

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on memory failure

Implemented in AT_CellularNetwork.

Request attach to network.

Parameters:

timeout

milliseconds to wait for attach response

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Dynamic downcast to a MeshInterface.

Definition at line 259 of file NetworkInterface.h.

Scans for operators module can reach.

Parameters:

operators	Container of reachable operators and their access technologies
ops_count	Number of found operators

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on memory failure NSAPI_ERROR_DEVICE_ERROR on other failures

Implemented in AT_CellularNetwork.

Sets radio access technology.

Parameters:

rat	Radio access technology

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_UNSUPPORTED if the given rat is RAT_UNKNOWN or inheriting target class has not implemented method set_access_technology_impl(...) OR return value of the inheriting target class set_access_technology_impl(...)

Implemented in AT_CellularNetwork.

Set blocking status of connect() which by default should be blocking.

Parameters:

blocking

true if connect is blocking

Returns:

NSAPI_ERROR_OK if PPP mode check errors from nsapi_ppp_set_blocking(...)

Implemented in AT_CellularNetwork.

Set CIoT optimizations.

Parameters:

supported_opt	Supported CIoT EPS optimizations.
preferred_opt	Preferred CIoT EPS optimizations.

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularNetwork.

Set the cellular network APN and credentials.

Parameters:

apn	Name of the network to connect to
type	Authentication type to use
username	Optional username for the APN
password	Optional password fot the APN

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on memory failure

Set the cellular network APN and credentials.

Parameters:

apn	Optional name of the network to connect to
username	Optional username for the APN
password	Optional password fot the APN

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on memory failure

Implemented in AT_CellularNetwork.

Enable or disable DHCP on the network.

Enables DHCP on connecting the network. Defaults to enabled unless a static IP address has been assigned. Requires that the network is disconnected.

Parameters:

dhcp	True to enable DHCP

Returns:

0 on success, negative error code on failure

Definition at line 48 of file NetworkInterface.cpp.

Set a static IP address.

Configures this network interface to use a static IP address. Implicitly disables DHCP, which can be enabled in set_dhcp. Requires that the network is disconnected.

Parameters:

ip_address	Null-terminated representation of the local IP address
netmask	Null-terminated representation of the local network mask
gateway	Null-terminated representation of the local gateway

Returns:

0 on success, negative error code on failure

Definition at line 43 of file NetworkInterface.cpp.

Request registering to network.

Parameters:

plmn	format is in numeric format or 0 for automatic network registration

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularNetwork.

Activate/deactivate listening of network events for the given RegistrationType.

This should be called after network class is created and ready to receive AT commands. After successful call network class starts to get information about network changes like registration statue, access technology, cell id...

Parameters:

type	RegistrationType to set urc on/off
on	Controls are urc active or not

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularNetwork.

Set the pdn type to be used.

Parameters:

stack_type

the stack type to be used.

Returns:

NSAPI_ERROR_OK on success NSAPI_ERROR_PARAMETER if modem does not support the given stack_type

Implemented in AT_CellularNetwork.

Dynamic downcast to a WiFiInterface.

Definition at line 253 of file NetworkInterface.h.