Macros | Typedefs | Enumerations | Functions

le_atServer_interface.h File Reference

#include "legato.h"
#include "le_atDefs_interface.h"

Go to the source code of this file.

Macros

#define LE_ATSERVER_TEXT_MAX_LEN   4096
 
#define LE_ATSERVER_CME_ERROR   "+CME ERROR: "
 
#define LE_ATSERVER_CMS_ERROR   "+CMS ERROR: "
 

Typedefs

typedef void(* le_atServer_DisconnectHandler_t) (void *)
 
typedef struct le_atServer_Cmd * le_atServer_CmdRef_t
 
typedef struct le_atServer_Device * le_atServer_DeviceRef_t
 
typedef struct le_atServer_Bridge * le_atServer_BridgeRef_t
 
typedef struct le_atServer_ErrorCode * le_atServer_ErrorCodeRef_t
 
typedef struct le_atServer_CommandHandler * le_atServer_CommandHandlerRef_t
 
typedef void(* le_atServer_CommandHandlerFunc_t) (le_atServer_CmdRef_t commandRef, le_atServer_Type_t type, uint32_t parametersNumber, void *contextPtr)
 
typedef void(* le_atServer_GetTextCallbackFunc_t) (le_atServer_CmdRef_t cmdRef, le_result_t result, const char *LE_NONNULL text, uint32_t len, void *contextPtr)
 

Enumerations

enum  le_atServer_Type_t { LE_ATSERVER_TYPE_ACT = 0, LE_ATSERVER_TYPE_PARA = 1, LE_ATSERVER_TYPE_TEST = 2, LE_ATSERVER_TYPE_READ = 3 }
 
enum  le_atServer_FinalRsp_t {
  LE_ATSERVER_OK = 0, LE_ATSERVER_NO_CARRIER = 1, LE_ATSERVER_ERROR = 2, LE_ATSERVER_NO_DIALTONE = 3,
  LE_ATSERVER_BUSY = 4
}
 
enum  le_atServer_AvailableDevice_t { LE_ATSERVER_ALL_DEVICES = 0, LE_ATSERVER_SPECIFIC_DEVICE = 1 }
 

Functions

void le_atServer_ConnectService (void)
 
le_result_t le_atServer_TryConnectService (void)
 
void le_atServer_SetServerDisconnectHandler (le_atServer_DisconnectHandler_t disconnectHandler, void *contextPtr)
 
void le_atServer_DisconnectService (void)
 
le_result_t le_atServer_Suspend (le_atServer_DeviceRef_t device)
 
le_result_t le_atServer_Resume (le_atServer_DeviceRef_t device)
 
le_atServer_DeviceRef_t le_atServer_Open (int fd)
 
le_result_t le_atServer_Close (le_atServer_DeviceRef_t device)
 
le_atServer_CmdRef_t le_atServer_Create (const char *LE_NONNULL name)
 
le_result_t le_atServer_Delete (le_atServer_CmdRef_t commandRef)
 
le_atServer_CommandHandlerRef_t le_atServer_AddCommandHandler (le_atServer_CmdRef_t commandRef, le_atServer_CommandHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_atServer_RemoveCommandHandler (le_atServer_CommandHandlerRef_t handlerRef)
 
le_result_t le_atServer_GetParameter (le_atServer_CmdRef_t commandRef, uint32_t index, char *parameter, size_t parameterSize)
 
le_result_t le_atServer_GetCommandName (le_atServer_CmdRef_t commandRef, char *name, size_t nameSize)
 
le_result_t le_atServer_GetDevice (le_atServer_CmdRef_t commandRef, le_atServer_DeviceRef_t *deviceRefPtr)
 
le_result_t le_atServer_SendIntermediateResponse (le_atServer_CmdRef_t commandRef, const char *LE_NONNULL intermediateRsp)
 
le_result_t le_atServer_SendFinalResponse (le_atServer_CmdRef_t commandRef, le_atServer_FinalRsp_t finalResponse, bool customStringAvailable, const char *LE_NONNULL finalRsp)
 
le_result_t le_atServer_SendFinalResultCode (le_atServer_CmdRef_t commandRef, le_atServer_FinalRsp_t finalResult, const char *LE_NONNULL pattern, uint32_t errorCode)
 
le_result_t le_atServer_SendUnsolicitedResponse (const char *LE_NONNULL unsolRsp, le_atServer_AvailableDevice_t availableDevice, le_atServer_DeviceRef_t device)
 
le_result_t le_atServer_EnableEcho (le_atServer_DeviceRef_t device)
 
le_result_t le_atServer_DisableEcho (le_atServer_DeviceRef_t device)
 
le_atServer_BridgeRef_t le_atServer_OpenBridge (int fd)
 
le_result_t le_atServer_CloseBridge (le_atServer_BridgeRef_t bridgeRef)
 
le_result_t le_atServer_AddDeviceToBridge (le_atServer_DeviceRef_t deviceRef, le_atServer_BridgeRef_t bridgeRef)
 
le_result_t le_atServer_RemoveDeviceFromBridge (le_atServer_DeviceRef_t deviceRef, le_atServer_BridgeRef_t bridgeRef)
 
void le_atServer_EnableVerboseErrorCodes (void)
 
void le_atServer_EnableExtendedErrorCodes (void)
 
void le_atServer_DisableExtendedErrorCodes (void)
 
le_atServer_ErrorCodeRef_t le_atServer_CreateErrorCode (uint32_t errorCode, const char *LE_NONNULL pattern)
 
le_result_t le_atServer_DeleteErrorCode (le_atServer_ErrorCodeRef_t errorCodeRef)
 
le_result_t le_atServer_SetVerboseErrorCode (le_atServer_ErrorCodeRef_t errorCodeRef, const char *LE_NONNULL verboseCode)
 
le_result_t le_atServer_GetTextAsync (le_atServer_CmdRef_t cmdRef, le_atServer_GetTextCallbackFunc_t callbackPtr, void *contextPtr)
 

Detailed Description

Legato AT Commands Server include file.

Copyright (C) Sierra Wireless Inc.

Macro Definition Documentation

◆ LE_ATSERVER_CME_ERROR

#define LE_ATSERVER_CME_ERROR   "+CME ERROR: "

CME error pattern

◆ LE_ATSERVER_CMS_ERROR

#define LE_ATSERVER_CMS_ERROR   "+CMS ERROR: "

CMS error pattern

◆ LE_ATSERVER_TEXT_MAX_LEN

#define LE_ATSERVER_TEXT_MAX_LEN   4096

Maximum text length.

Typedef Documentation

◆ le_atServer_BridgeRef_t

typedef struct le_atServer_Bridge* le_atServer_BridgeRef_t

Reference type for a AT commands server / AT commands client bridge.

◆ le_atServer_CmdRef_t

typedef struct le_atServer_Cmd* le_atServer_CmdRef_t

Reference type for an AT command.

◆ le_atServer_CommandHandlerFunc_t

typedef void(* le_atServer_CommandHandlerFunc_t) (le_atServer_CmdRef_t commandRef, le_atServer_Type_t type, uint32_t parametersNumber, void *contextPtr)

Handler for the AT command processing.

Note
The argument "parametersNumber" is set only when "type" parameter value is LE_AT_SERVER_TYPE_PARA

◆ le_atServer_CommandHandlerRef_t

typedef struct le_atServer_CommandHandler* le_atServer_CommandHandlerRef_t

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

◆ le_atServer_DeviceRef_t

typedef struct le_atServer_Device* le_atServer_DeviceRef_t

Reference type for a AT command device.

◆ le_atServer_DisconnectHandler_t

typedef void(* le_atServer_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

◆ le_atServer_ErrorCodeRef_t

typedef struct le_atServer_ErrorCode* le_atServer_ErrorCodeRef_t

Reference type for an error code.

◆ le_atServer_GetTextCallbackFunc_t

typedef void(* le_atServer_GetTextCallbackFunc_t) (le_atServer_CmdRef_t cmdRef, le_result_t result, const char *LE_NONNULL text, uint32_t len, void *contextPtr)

Get text callback

Returns
  • LE_OK: The function succeeded
  • LE_IO_ERROR: An io error happened and the function couldn't read from the device
  • LE_FORMAT_ERROR: Received an invalid character or an invalid sequence
  • LE_FAULT: Failed to remove backspaces

Enumeration Type Documentation

◆ le_atServer_AvailableDevice_t

enum le_atServer_AvailableDevice_t

Device availability.

Enumerator
LE_ATSERVER_ALL_DEVICES 

action will be done on all bound devices

LE_ATSERVER_SPECIFIC_DEVICE 

action will be done on a specified device

◆ le_atServer_FinalRsp_t

enum le_atServer_FinalRsp_t

Final response.

Enumerator
LE_ATSERVER_OK 

AT command successfully treated.

LE_ATSERVER_NO_CARRIER 

Connection terminated.

LE_ATSERVER_ERROR 

Error in AT command treatement.

LE_ATSERVER_NO_DIALTONE 

No dialtone detected.

LE_ATSERVER_BUSY 

Busy signal detected.

◆ le_atServer_Type_t

enum le_atServer_Type_t

Received AT command type.

Enumerator
LE_ATSERVER_TYPE_ACT 

Action AT command (e.g. 'AT+CMD')

LE_ATSERVER_TYPE_PARA 

AT command received with parameters (e.g. 'AT+CMD=x,y')

LE_ATSERVER_TYPE_TEST 

Test AT command (e.g. 'AT+CMD=?')

LE_ATSERVER_TYPE_READ 

Read AT command (e.g. 'AT+CMD?')

Function Documentation

◆ le_atServer_AddCommandHandler()

le_atServer_CommandHandlerRef_t le_atServer_AddCommandHandler ( le_atServer_CmdRef_t  commandRef,
le_atServer_CommandHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Add handler function for EVENT 'le_atServer_Command'

This event provides information when the AT command is detected.

Parameters
[in]commandRefAT command reference
[in]handlerPtrHandler to called when the AT command is detected
[in]contextPtr

◆ le_atServer_AddDeviceToBridge()

le_result_t le_atServer_AddDeviceToBridge ( le_atServer_DeviceRef_t  deviceRef,
le_atServer_BridgeRef_t  bridgeRef 
)

This function adds a device to an opened bridge.

Returns
  • LE_OK The function succeeded.
  • LE_BUSY The device is already used by the bridge.
  • LE_FAULT The function failed to add the device to the bridge.
Parameters
[in]deviceRefDevice reference to add to the bridge
[in]bridgeRefBridge refence

◆ le_atServer_Close()

le_result_t le_atServer_Close ( le_atServer_DeviceRef_t  device)

This function closes the AT server session on the requested device.

Returns
  • LE_OK The function succeeded.
  • LE_BAD_PARAMETER Invalid device reference.
  • LE_BUSY The requested device is busy.
  • LE_FAULT Failed to stop the server, check logs for more information.
Parameters
[in]devicedevice to be unbound

◆ le_atServer_CloseBridge()

le_result_t le_atServer_CloseBridge ( le_atServer_BridgeRef_t  bridgeRef)

This function closes an opened bridge.

Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to close the bridge.
  • LE_BUSY The bridge is in use (devices references have to be removed first).
Parameters
[in]bridgeRefBridge reference

◆ le_atServer_ConnectService()

void le_atServer_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.

◆ le_atServer_Create()

le_atServer_CmdRef_t le_atServer_Create ( const char *LE_NONNULL  name)

This function created an AT command and register it into the AT parser.

Returns
  • Reference to the AT command.
  • NULL if an error occurs.
Parameters
[in]nameAT command name string

◆ le_atServer_CreateErrorCode()

le_atServer_ErrorCodeRef_t le_atServer_CreateErrorCode ( uint32_t  errorCode,
const char *LE_NONNULL  pattern 
)

This function creates a custom error code.

Returns
  • ErrorCode Reference to the created error code
  • NULL Function failed to create the error code
Note
This function fails to create the error code if the combinaison (errorCode, pattern) already exists or if the errorCode number is lower than 512.
Parameters
[in]errorCodeNumerical error code
[in]patternPrefix of the response message

◆ le_atServer_Delete()

le_result_t le_atServer_Delete ( le_atServer_CmdRef_t  commandRef)

This function deletes an AT command (i.e. unregister from the AT parser).

Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to delete the command.
  • LE_BUSY Command is in progress.
Parameters
[in]commandRefAT command reference

◆ le_atServer_DeleteErrorCode()

le_result_t le_atServer_DeleteErrorCode ( le_atServer_ErrorCodeRef_t  errorCodeRef)

This function deletes a custom error code.

Returns
  • LE_OK The function succeeded
  • LE_FAULT The function failed to delete the error code
Parameters
[in]errorCodeRefError code reference

◆ le_atServer_DisableEcho()

le_result_t le_atServer_DisableEcho ( le_atServer_DeviceRef_t  device)

This function disables echo on the selected device.

Returns
  • LE_OK The function succeeded.
  • LE_BAD_PARAMETER Invalid device reference.
Parameters
[in]devicedevice reference

◆ le_atServer_DisableExtendedErrorCodes()

void le_atServer_DisableExtendedErrorCodes ( void  )

This function disables extended error codes on the selected device.

◆ le_atServer_DisconnectService()

void le_atServer_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_atServer_EnableEcho()

le_result_t le_atServer_EnableEcho ( le_atServer_DeviceRef_t  device)

This function enables echo on the selected device.

Returns
  • LE_OK The function succeeded.
  • LE_BAD_PARAMETER Invalid device reference.
Parameters
[in]devicedevice reference

◆ le_atServer_EnableExtendedErrorCodes()

void le_atServer_EnableExtendedErrorCodes ( void  )

This function enables extended error codes on the selected device.

◆ le_atServer_EnableVerboseErrorCodes()

void le_atServer_EnableVerboseErrorCodes ( void  )

This function enables verbose error codes on the selected device.

◆ le_atServer_GetCommandName()

le_result_t le_atServer_GetCommandName ( le_atServer_CmdRef_t  commandRef,
char *  name,
size_t  nameSize 
)

This function can be used to get the AT command string.

Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to get the AT command string.
Parameters
[in]commandRefAT command reference
[out]nameAT command string
[in]nameSize

◆ le_atServer_GetDevice()

le_result_t le_atServer_GetDevice ( le_atServer_CmdRef_t  commandRef,
le_atServer_DeviceRef_t *  deviceRefPtr 
)

This function can be used to get the device reference in use for an AT command specified with its reference.

Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to get the AT command string.
Parameters
[in]commandRefAT command reference
[out]deviceRefPtrDevice reference

◆ le_atServer_GetParameter()

le_result_t le_atServer_GetParameter ( le_atServer_CmdRef_t  commandRef,
uint32_t  index,
char *  parameter,
size_t  parameterSize 
)

This function can be used to get the parameters of a received AT command.

Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to get the requested parameter.
Note
If the parameter is parsed with quotes, the quotes are removed when retrieving the parameter value using this API. If a parmeter is not parsed with quotes, that parameter is converted to uppercase equivalent.
Parameters
[in]commandRefAT command reference
[in]indexagument index
[out]parameterparameter value
[in]parameterSize

◆ le_atServer_GetTextAsync()

le_result_t le_atServer_GetTextAsync ( le_atServer_CmdRef_t  cmdRef,
le_atServer_GetTextCallbackFunc_t  callbackPtr,
void *  contextPtr 
)

This function allows the user to register a le_atServer_GetTextCallback_t callback to retrieve text and sends a prompt <CR><LF><greater_than><SPACE> on the current command's device.

Returns
  • LE_OK The function succeeded.
  • LE_BAD_PARAMETER Invalid device or command reference.
Parameters
[in]cmdRefAT command reference
[in]callbackPtrGet text callback
[in]contextPtr

◆ le_atServer_Open()

le_atServer_DeviceRef_t le_atServer_Open ( int  fd)

This function opens an AT server session on the requested device.

Returns
  • Reference to the requested device.
  • NULL if the device is not available or fd is a BAD FILE DESCRIPTOR.
Note
Make sure to duplicate (man dup) your file descriptor before opening a server session to be able to use the suspend/resume feature
Parameters
[in]fdFile descriptor.

◆ le_atServer_OpenBridge()

le_atServer_BridgeRef_t le_atServer_OpenBridge ( int  fd)

This function opens a AT commands server bridge. All unknown AT commands will be sent on this alternative file descriptor thanks to the AT client Service.

Returns
  • Reference to the requested bridge.
  • NULL if the device can't be bridged
Parameters
[in]fdFile descriptor.

◆ le_atServer_RemoveCommandHandler()

void le_atServer_RemoveCommandHandler ( le_atServer_CommandHandlerRef_t  handlerRef)

Remove handler function for EVENT 'le_atServer_Command'

Parameters
[in]handlerRef

◆ le_atServer_RemoveDeviceFromBridge()

le_result_t le_atServer_RemoveDeviceFromBridge ( le_atServer_DeviceRef_t  deviceRef,
le_atServer_BridgeRef_t  bridgeRef 
)

This function removes a device from a bridge

Returns
  • LE_OK The function succeeded.
  • LE_NOT_FOUND The device is not isued by the specified bridge
  • LE_BUSY The device is currently in use
  • LE_FAULT The function failed to add the device to the bridge.
Parameters
[in]deviceRefDevice reference to add to the bridge
[in]bridgeRefBridge refence

◆ le_atServer_Resume()

le_result_t le_atServer_Resume ( le_atServer_DeviceRef_t  device)

Resume server / enter command mode

When this function is called the server resumes monitoring the fd for events and is able to interpret AT commands again.

Returns
  • LE_OK Success.
  • LE_BAD_PARAMETER Invalid device reference.
  • LE_FAULT Device not monitored
Parameters
[in]devicedevice to be resumed

◆ le_atServer_SendFinalResponse()

le_result_t le_atServer_SendFinalResponse ( le_atServer_CmdRef_t  commandRef,
le_atServer_FinalRsp_t  finalResponse,
bool  customStringAvailable,
const char *LE_NONNULL  finalRsp 
)

This function can be used to send the final response.

Deprecated:
le_atServer_SendFinalResponse() should not be used anymore and will be removed soon. It has been replaced by le_atServer_SendFinalResultCode()
Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to send the final response.
Parameters
[in]commandRefAT command reference
[in]finalResponseFinal response to be sent
[in]customStringAvailableCustom final response has to be sent instead of the default one.
[in]finalRspcustom final response string

◆ le_atServer_SendFinalResultCode()

le_result_t le_atServer_SendFinalResultCode ( le_atServer_CmdRef_t  commandRef,
le_atServer_FinalRsp_t  finalResult,
const char *LE_NONNULL  pattern,
uint32_t  errorCode 
)

This function can be used to send the final result code.

Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to send the final result code.
Parameters
[in]commandRefAT command reference
[in]finalResultFinal result code to be sent
[in]patternPrefix of the return message
[in]errorCodeNumeric error code

◆ le_atServer_SendIntermediateResponse()

le_result_t le_atServer_SendIntermediateResponse ( le_atServer_CmdRef_t  commandRef,
const char *LE_NONNULL  intermediateRsp 
)

This function can be used to send an intermediate response.

Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to send the intermediate response.
Parameters
[in]commandRefAT command reference
[in]intermediateRspIntermediate response to be sent

◆ le_atServer_SendUnsolicitedResponse()

le_result_t le_atServer_SendUnsolicitedResponse ( const char *LE_NONNULL  unsolRsp,
le_atServer_AvailableDevice_t  availableDevice,
le_atServer_DeviceRef_t  device 
)

This function can be used to send the unsolicited response.

Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to send the unsolicited response.
Parameters
[in]unsolRspUnsolicited response to be sent
[in]availableDevicedevice to send the unsolicited response
[in]devicedevice reference where the unsolicited response has to be sent

◆ le_atServer_SetServerDisconnectHandler()

void le_atServer_SetServerDisconnectHandler ( le_atServer_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_atServer_SetVerboseErrorCode()

le_result_t le_atServer_SetVerboseErrorCode ( le_atServer_ErrorCodeRef_t  errorCodeRef,
const char *LE_NONNULL  verboseCode 
)

This function adds a verbose message to a specified error code

Returns
  • LE_OK The function succeeded
  • LE_FAULT The function failed to set the verbose message
Parameters
[in]errorCodeRefError code reference
[in]verboseCodeVerbose message

◆ le_atServer_Suspend()

le_result_t le_atServer_Suspend ( le_atServer_DeviceRef_t  device)

Suspend server / enter data mode

When this function is called the server stops monitoring the fd for events hence no more I/O operations are done on the fd by the server.

Returns
  • LE_OK Success.
  • LE_BAD_PARAMETER Invalid device reference.
  • LE_FAULT Device not monitored
Parameters
[in]devicedevice to be suspended

◆ le_atServer_TryConnectService()

le_result_t le_atServer_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.