le_cellnet_interface.h File Reference

#include "legato.h"
#include "le_sim_interface.h"

Go to the source code of this file.

Typedefs

typedef void(* le_cellnet_DisconnectHandler_t) (void *)
 
typedef struct le_cellnet_RequestObj * le_cellnet_RequestObjRef_t
 
typedef struct le_cellnet_StateEventHandler * le_cellnet_StateEventHandlerRef_t
 
typedef void(* le_cellnet_StateHandlerFunc_t) (le_cellnet_State_t state, void *contextPtr)
 

Enumerations

enum  le_cellnet_State_t {
  LE_CELLNET_RADIO_OFF = 0, LE_CELLNET_REG_EMERGENCY = 1, LE_CELLNET_REG_HOME = 2, LE_CELLNET_REG_ROAMING = 3,
  LE_CELLNET_REG_UNKNOWN = 4, LE_CELLNET_SIM_ABSENT = 5
}
 

Functions

void le_cellnet_ConnectService (void)
 
le_result_t le_cellnet_TryConnectService (void)
 
void le_cellnet_SetServerDisconnectHandler (le_cellnet_DisconnectHandler_t disconnectHandler, void *contextPtr)
 
void le_cellnet_DisconnectService (void)
 
le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler (le_cellnet_StateHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_cellnet_RemoveStateEventHandler (le_cellnet_StateEventHandlerRef_t handlerRef)
 
le_cellnet_RequestObjRef_t le_cellnet_Request (void)
 
void le_cellnet_Release (le_cellnet_RequestObjRef_t cellNetRef)
 
le_result_t le_cellnet_SetSimPinCode (le_sim_Id_t simId, const char *LE_NONNULL pinCode)
 
le_result_t le_cellnet_GetSimPinCode (le_sim_Id_t simId, char *pinCode, size_t pinCodeSize)
 
le_result_t le_cellnet_GetNetworkState (le_cellnet_State_t *statePtr)
 

Detailed Description

Legato Cellular Network include file.

Typedef Documentation

typedef void(* le_cellnet_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

typedef struct le_cellnet_RequestObj* le_cellnet_RequestObjRef_t

Reference returned by Request function and used by Release function

typedef struct le_cellnet_StateEventHandler* le_cellnet_StateEventHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_cellnet_StateEvent'

typedef void(* le_cellnet_StateHandlerFunc_t) (le_cellnet_State_t state,void *contextPtr)

Handler for network state changes

Enumeration Type Documentation

Cellular Network states.

Enumerator
LE_CELLNET_RADIO_OFF 

The radio is switched-off.

LE_CELLNET_REG_EMERGENCY 

Only emergency calls are allowed.

LE_CELLNET_REG_HOME 

Registered, home network.

LE_CELLNET_REG_ROAMING 

Registered to a roaming network.

LE_CELLNET_REG_UNKNOWN 

Unknown state.

LE_CELLNET_SIM_ABSENT 

No SIM card available.

Function Documentation

le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler ( le_cellnet_StateHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Add handler function for EVENT 'le_cellnet_StateEvent'

This event provides information on network state changes

Parameters
[in]handlerPtr
[in]contextPtr
void le_cellnet_ConnectService ( void  )

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

void le_cellnet_DisconnectService ( void  )

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

le_result_t le_cellnet_GetNetworkState ( le_cellnet_State_t statePtr)

Retrieve the current cellular network state.

Returns
  • LE_OK The function succeeded.
  • LE_FAILED The function failed
  • LE_BAD_PARAMETER A bad parameter was passed.
Note
If the caller passes a null pointer to this function, this is a fatal error and the function will not return.
Parameters
[out]statePtrCellular network state.
le_result_t le_cellnet_GetSimPinCode ( le_sim_Id_t  simId,
char *  pinCode,
size_t  pinCodeSize 
)

Retrieve the PIN code from the secure storage.

Returns
  • LE_OUT_OF_RANGE Invalid simId
  • LE_NOT_FOUND PIN code is not found in the secure storage.
  • LE_OVERFLOW PIN code exceeds the maximum length of 8 digits.
  • LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
  • LE_OK The function succeeded.
  • LE_FAULT If there are some other errors.
Parameters
[in]simIdSIM identifier.
[out]pinCodeRead the PIN code from the secure storage.
[in]pinCodeSize
void le_cellnet_Release ( le_cellnet_RequestObjRef_t  cellNetRef)

Release a cellular network

Parameters
[in]cellNetRefReference to a cellular network request.
void le_cellnet_RemoveStateEventHandler ( le_cellnet_StateEventHandlerRef_t  handlerRef)

Remove handler function for EVENT 'le_cellnet_StateEvent'

Parameters
[in]handlerRef
le_cellnet_RequestObjRef_t le_cellnet_Request ( void  )

Request a cellular network

Returns
  • A reference to the cellular network
  • 0 (zero) if the network requested could not be processed
void le_cellnet_SetServerDisconnectHandler ( le_cellnet_DisconnectHandler_t  disconnectHandler,
void *  contextPtr 
)

Set handler called when server disconnection is detected.

When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.

le_result_t le_cellnet_SetSimPinCode ( le_sim_Id_t  simId,
const char *LE_NONNULL  pinCode 
)

Set the PIN code in the secure storage.

Returns
  • LE_OUT_OF_RANGE Invalid simId
  • LE_FORMAT_ERROR PIN code is not in string format.
  • LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
  • LE_OK The function succeeded.
  • LE_FAULT The function failed on any other errors
Note
If PIN code is too long (max 8 digits), it is a fatal error, the function will not return.
Parameters
[in]simIdSIM identifier.
[in]pinCodePIN code to insert in the secure storage.
le_result_t le_cellnet_TryConnectService ( void  )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

Returns
  • LE_OK if the client connected successfully to the service.
  • LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  • LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  • LE_COMM_ERROR if the Service Directory cannot be reached.