Cellular data service (CDS) control object for OS-level processes
The cellular data services controller (CDSC) uses logical (symbolic) names to identify cellular data connections. This allows applications to reference a well known set of connections that's consistent across carriers. CDSC then performs the mapping to carrier-specific connection information based on the current runtime configuration (SIM, network, RAT, etc.).
The supported connections are listed in the following table:
| Connection Logical Name | Description |
|---|---|
| internet | Represents the default cellular data connection to the internet. Usually becomes part of the default route. |
| mms | Connection for Multimedia Messaging Services. |
| carrier_admin | Represents an administrative connection. If available, it's typically a secured zero-cost connection available to specific applications and services. |
| carrier_apps | Represents a special connection for use by specific applications (for example, certain carriers may provide this connection for their branded applications). |
| plan_admin | Represents a connection used for administration of pre-paid and other related plan services. |
| a_gps | Carrier may define a separate APN for assisted GPS server access. |
| carrier_800 | Represents a connection where the carrier charges the destination for usage. |
| streaming | Connection for alternate streaming channels. |
Commands sent to the pps/services/cds/cnice/control objects are of the form:
msg::command_string\nid::msg_ID\ndat:json:{data}
Responses always reflect the command_string and msg_ID that were sent in the message. Depending on the command, the response may also include additional information (often JSON-encoded) in the dat attribute, along with an error code (err attribute), if applicable:
res::command_string
id::msg_ID
dat:json:additional_data
err:n:{error_code}
Request the activation of the specified logical connection.
msg::connect
id:msg_ID
dat:json:
{
"name":"logical_name>",
"retries":"number_of_retries"
}
where name is the logical connection name and retries is an optional
parameter that specifies the number of times CDSC will attempt to connect.
If retries is not provided, CDSC will keep trying indefinitely.
The connect command sequence is asynchronous. If the response indicates success, this means only that the radio layer has accepted the request and has started the sequence of activating the connection. The actual result of the connection sequence is published to the logical connection's status attribute. Clients don't have to implement timeout logic for waiting for a result because the radio layer is guaranteed to return a result of some sort.
If retries is not provided, CDSC will keep retrying the connection. The service's active attribute in the status object is set to true; the connected attribute is false until a connection is established. If retries is provided and a connection can't be established within the specified number of retries, CDSC gives up trying connect and returns to the disconnected state. It's up to the applications to implement their own retry logic to handle connection failures.
What actually takes place during a specific connect request depends on the configuration of the connection and its current state:
To allow CDSC to properly manage the life cycle of an "on demand" connection (not always on), an opaque connection ID value is returned to clients in the response. The client must track this ID and provide it when making the disconnect request. This allows CDSC to accurately track client references on the connection and close the connection when there are no applications using it. If a connection is closed for any reason, or a connect request fails, CDSC disards all existing connection references. Clients are expected to make a new connect request (if required) in these situations, resulting in a new connection ID for each request. If a client uses a "stale" connection ID in a disconnect request, the request is ignored.
It is highly recommended that client applications call connect and disconnect, even if a connection is currently active (as per the status object). If a client decides to bind to a connection's net interface without calling connect, there is a risk that CDSC will deem the connection unused and close it. By calling connect, clients ensure CDSC will keep the connection active at least until the client calls disconnect.
res::connect
id:msg_ID
dat:json:{"already_connected":true|false,"connect_id":"connect_id"}
err:n:error_code
The following parameters and attributes may be returned in the response:
Request the deactivation of the specified logical connection.
The disconnect command has the following form:
msg::disconnect
id:msg_ID
dat:json:
{
"name":"logical_name",
"connect_id":"connect_id",
"force":true|false
}
CDSC sends the disconnect response to the client in reply to the disconnect command. The response has the following form:
res::disconnect
id::msg_ID
dat:json:
{
"already_disconnected":true|false,
"always_on":true|false,
"ref_remaining":true|false
}
err:n:error_code
The following parameters and attributes may be returned in the response:
Query the service statistics of the specified logical service.
The get_service_stats command has the following form:
msg::get_service_stats
id:msg_ID
dat:json:{
"name":"logical_name",
"timeUnit":"sec|msec|usec|nsec",
"dataUnit":"Byte|KB|MB|GB"
}
where:
CDSC sends the get_service_stats response to the client in reply to the get_service_stats command. The response has the following form:
res::get_service_stats
id::msg_ID
dat:json:{
"idleTime":value,
"bytesSent":value,
"bytesReceived":value
}
err:n:error_code>
The following attributes and parameters may be returned in the response:
Turn data services on or off. This value is persisted across device reboot.
The set_data_service_mode command has one of the following forms:
msg::set_data_service_mode id::msg_ID dat::ON|OFF
or
msg::set_data_service_mode
id::msg_ID
dat:json:
{
"data_service_mode":"ON|OFF",
"remember_user_enabled_data_roaming":true|false
}
where remember_user_enabled_data_roaming, if true, indicates that the setting of user_enabled_data_roaming is maintained. If false (default), the user_enabled_data_roaming state is cleared. In order for the user_enabled_data_roaming state to be maintained across a cycle of the data services mode, remember_user_enabled_data_roaming must be specified as true in both the ON and OFF messages.
CDSC sends the set_data_service_mode response to the client in reply to the set_data_service_mode command. The response has the following form:
res::set_data_service_mode id::msg_ID err:n:error_code
The following code may be returned in the err attribute in the case of an error:
Set the data services behaviour while roaming. This value is persisted across device reboot.
msg::set_data_roaming_mode id::msg_ID dat::ON|OFF|PROMPT
where the possible settings are as follows:
CDSC sends the set_data_roaming_mode response to the client in reply to the set_data_roaming_mode command. The response has the following form:
res::set_data_roaming_mode id::msg_ID err:n:error_code
The following code may be returned in the case of an error:
Turn data services back on when they are currently turned off for roaming. The setting specified though this command is subsequently published in the user_enabled_data_roaming status attribute. This setting is maintained until data services are turned off or until the device ceases to be in a data roaming state.
The enable_data_roaming command has the following form:
msg::enable_data_roaming id::msg_ID dat::YES|NO
CDSC sends the enable_data_roaming response to the client in reply to the enable_data_roaming command. The response has the following form:
res::enable_data_roaming id::msg_ID err:n:error_code
One of the following codes may be returned in the case of an error:
Assert that a critical connection request is prioritized over other active connections.
The focus command has the following form:
msg::focus
id::msg_ID
dat:json:{
"name":"logical_name",
"immediate":true|false
}
where:
CDSC sends the focus response to the client in reply to the focus command. The response has the following form:
res::focus id::msg_ID err:n:error_code
The following error code (err) may be returned in the case of an error:
Remove the focus previously placed on the specified connection return to normal connection prioritization.
The defocus command has the following form:
msg::defocus
id::msg_ID
dat:json:{
"name":"logical_name"
}
where name is the name of logical connection to remove the focus from (required).
CDSC sends the defocus response to the client in reply to the defocus command. The response has the following form:
res::defocus id::msg_ID err:n:error_code
The following error code (err) may be returned in the case of an error:
msg::connect
id:msg_ID
dat:json:
{
"name":"mms",
"retries":"10"
}
res::connect
id:msg_ID
dat:json:{"already_connected":"true","connect_id":"connect_id"}
res::connect id:msg_ID err:n:16
msg::disconnect
id:msg_ID
dat:json:{"name":"plan_admin","connect_id":"connect_id"}
res::disconnect
id:msg_ID
dat:json:{"ref_remaining":true}