RIL API

Header File

#include <ril/ril.h>

Functions

int ril_send_atcommand(const char *cmd, atrsp_callback_f cb, void *arg, unsigned int timeout, int wait)

Execute and AT command. This function implements sending AT command with the result being returned synchronously. The response of the AT command will be reported to the callback function

Parameters:

cmd – [in] AT command string
cb – [in] processing callback function atrsp_callback_f
arg – [in] User argument passed to callback function
timeout – [in] Timeout for command execution
wait – [in] Wait for RIL to be available (TRUE) or not (FALSE). If wait is false, function returns immediately if RIL is unavailable. If true function will wait for RIL availability until timeout occurs.

Returns:

RIL return code ril_rc_e

int ril_write_data(const void *data, int len)

Send data to RIL core

Parameters:

data – [in] Pointer to data to be sent
len – [in] Length of data

Returns:

On success, this function returns actual length of data written, negative code on error

int ril_urc_attach(const char *keyword, urc_handler_f callback)

Attach URC to RIL core

Parameters:

keyword – [in] URC Keyword
callback – [in] URC handler function

Returns:

0 on success, negative value on error

int ril_urc_detach(const char *keyword)

Detach URC from RIL core

Parameters:: keyword – [in] URC keyword
Returns:: 0 on success, negative value on error

int ril_lock(int wait)

Get exclusive access to Radio interface layer. This lock is only an advisory lock for RIL.

Note

ril_lock(), ril_trylock() and ril_unlock() should be called from same task

Parameters:: wait – [in] true to wait for lock, false to return immediately
Returns:: 0 on success, -EWOULDBLOCK on error or when lock is unavailable

int ril_trylock(int wait_ms)

Get exclusive access to Radio interface layer. This lock is only an advisory lock for RIL.

Note

ril_lock(), ril_trylock() and ril_unlock() should be called from same task

Parameters:: wait_ms – [in] Wait time in milliseconds
Returns:: 0 on success, -EWOULDBLOCK on error or when lock is unavailable

void ril_unlock(void): Unlock RIL layer

Note

ril_lock(), ril_trylock() and ril_unlock() should be called from same task

Structures

struct ril_callinfo_t

Incoming call phone info

Public Members

int type: Incoming call type ril_calltype_e

char number[PHONE_NUMBER_MAX_LEN]: Phone number as null terminated string

Macros

RIL_MAX_URC_PREFIX_LEN: ril.h Maximum allowed URC keyword length

PHONE_NUMBER_MAX_LEN: Maximum phone number length

Type Definitions

typedef void (*urc_handler_f)(const char *strURC, void *reserved)

URC handler function type

Param strURC:: Incoming URC line
Param reserved:: reserved (unused)

typedef int (*atrsp_callback_f)(char *line, uint32_t len, void *arg)

AT command response processing function

Param line:: Incoming response line
Param len:: Length of response string
Param arg:: User argument passed via ril_send_atcommand
Return:: RIL response return code ril_resp_rc

typedef void (*ril_recvcb_f)(uint8_t *ptrData, uint32_t dataLen, void *reserved)

RIL receive core data callback function

Param ptrData:: Incoming data from RIL core
Param dataLen:: Length of incoming data
Param reserved:: Reserved (unused)

Enumerations

enum sysinitstate_e

System Initialization status

Values:

enumerator SYS_STATE_START: System started

enumerator SYS_STATE_ATOK: System ready for AT commands

enumerator SYS_STATE_PHBOK: Device is ready to make/receive calls

enumerator SYS_STATE_SMSOK: SIM card is ready for SMS

enum simstate_e

Definition for SIM Card State

Values:

enumerator SIM_STAT_NOT_INSERTED: SIM card not inserted

enumerator SIM_STAT_READY: SIM card ready, no further action required

enumerator SIM_STAT_PIN_REQ: ME waiting for SIM PIN

enumerator SIM_STAT_PUK_REQ: ME waiting for SIM PUK

enumerator SIM_STAT_PH_PIN_REQ: ME waiting for Phone to SIM card (anti-theft)

enumerator SIM_STAT_PH_PUK_REQ: ME waiting for SIM PUK (anti-theft)

enumerator SIM_STAT_PIN2_REQ: SIM PIN2 request (2, e.g. it is possible to edit the FDN book only if preceding command was acknowledged with +CME ERROR:17)

enumerator SIM_STAT_PUK2_REQ: SIM PUK2 request (Possible only if preceding command was acknowledged with error +CME ERROR: 18)

enumerator SIM_STAT_BUSY: SIM card busy

enumerator SIM_STAT_NOT_READY: SIM card not ready

enumerator SIM_STAT_UNSPECIFIED: Unknown error

enum networkstate_e

Network Registration status

Values:

enumerator NW_STAT_NOT_REGISTERED: Not register and not searching

enumerator NW_STAT_REGISTERED_HOME: Registered and in home network

enumerator NW_STAT_SEARCHING: Not registered and Searching network

enumerator NW_STAT_REG_DENIED: Registration is denied

enumerator NW_STAT_UNKNOWN: Unknown registration

enumerator NW_STAT_REGISTERED_ROAMING: Registered and in Roaming

enumerator NW_STAT_SMSONLY_HOME: 4G LTE Only: Registered for SMS only in home network

enumerator NW_STAT_SMSONLY_ROAMING: 4G LTE Only: Registered for SMS only in Roaming network

enum networkmode_e

Network Mode value

Values:

enumerator NW_MODE_UNKNOWN: Unknown mode

enumerator NW_MODE_GSM: GSM Mode

enumerator NW_MODE_LTE: LTE Mode

enum cfunstate_e

Phone functionality state

Values:

enumerator CFUN_STATE_0: Minimal functionality

enumerator CFUN_STATE_1: Full functionality

enumerator CFUN_STATE_4: Disable phone from both transmit ting and receive ing RF signals

enum callstatus_e

Call status

Values:

enumerator CALL_STATE_ERROR: Error

enumerator CALL_STATE_OK: Status OK

enumerator CALL_STATE_BUSY: Response “BUSY”

enumerator CALL_STATE_NO_ANSWER: Response “NO_ANSWER”

enumerator CALL_STATE_NO_CARRIER: Response “NO_CARRIER”

enumerator CALL_STATE_NO_DIALTONE: Response “NO_DIALTONE”

enumerator CALL_STATE_END: CALL_STATE_END

enum vbattind_e

Voltage Indication Type

Values:

enumerator VBATT_UNDER_WRN: Warning: Under voltage

enumerator VBATT_UNDER_PDN: Warning: Under voltage power-down

enumerator VBATT_OVER_WRN: Warning: Over voltage

enumerator VBATT_OVER_PDN: Warning: Over voltage power-down

enum sysurc_e

URC Codes

Values:

enumerator URC_SYS_BEGIN

enumerator URC_SYS_INIT_STATE_IND: Indication for module initialization state during boot stage, parameter value as sysinitstate_e

enumerator URC_SIM_CARD_STATE_IND: Indication for SIM card state (state change), parameter value as simstate_e

enumerator URC_GSM_NW_STATE_IND: Indication for GSM network state (state change), parameter value as networkstate_e

enumerator URC_GPRS_NW_STATE_IND: Indication for GPRS network state (state change), parameter value as networkstate_e

enumerator URC_EGPRS_NW_STATE_IND: Indication for EPS Network registration status, parameter value as networkstate_e

enumerator URC_CFUN_STATE_IND: Indication for CFUN state, with parameters as one of cfunstate_e

enumerator URC_COMING_CALL_IND: Indication for coming call with parameter as ril_callinfo_t

enumerator URC_CALL_STATE_IND: Indication for call state (state change), parameter value as callstatus_e

enumerator URC_NEW_SMS_IND: Indication for new short message, parameter value as index of incoming SMS

enumerator URC_MODULE_VOLTAGE_IND: Indication for abnormal voltage of module supply power, parameter value as vbattind_e

enumerator URC_ALARM_RING_IND: Indication for clock alarm.

enumerator URC_STKPCI_RSP_IND: Indication for un-handled STKPCI responses, Only when SIM Toolkit is enabled, Parameter value is incoming +STKPCI response as null terminated string

enumerator URC_RRC_STATUS_IND: 4G LTE & NBIoT RRC Status update

enumerator URL_NW_MODE_CHANGE_IND: Indication for change of network mode, only available on 4G LTE modules

enumerator URC_SYS_END

enumerator URC_END: Unhandled URC response

enum ril_resp_rc

Return code for AT command response process callback function If callback function returns RIL_ATRSP_CONTINUE, ril_send_atcommand will continue to block and process incoming response until callback function returns a success or fail response.

Values:

enumerator RIL_ATRSP_FAILED: AT command response processing failed

enumerator RIL_ATRSP_SUCCESS: AT command response processing success

enumerator RIL_ATRSP_CONTINUE: Continue processing incoming response of AT command

enum ril_rc_e

RIL Return code

Values:

enumerator RIL_AT_SUCCESS: AT Command executed successfully

enumerator RIL_AT_FAILED: AT Command execution failed

enumerator RIL_AT_TIMEOUT: AT command sent but response timeout

enumerator RIL_AT_BUSY: RIL is busy

enumerator RIL_AT_INVALID_PARAM: Invalid parameter

enumerator RIL_AT_UNINITIALIZED: RIL is not initialized

enum ril_calltype_e

Incoming call type

Values:

enumerator MD_VOICE_CALL_TYPE_VOICE: Voice call

enumerator MD_VOICE_CALL_TYPE_VIDEO: Video call