Zephyr API 3.6.99
Loading...
Searching...
No Matches
chat.h File Reference
#include <zephyr/kernel.h>
#include <zephyr/types.h>
#include <zephyr/device.h>
#include <zephyr/sys/ring_buffer.h>
#include <zephyr/modem/pipe.h>
#include <zephyr/modem/stats.h>

Go to the source code of this file.

Data Structures

struct  modem_chat_match
 Modem chat match. More...
 
struct  modem_chat_script_chat
 Modem chat script chat. More...
 
struct  modem_chat_script
 Modem chat script. More...
 
struct  modem_chat
 Chat instance internal context. More...
 
struct  modem_chat_config
 Chat configuration. More...
 

Macros

#define MODEM_CHAT_MATCH(_match, _separators, _callback)
 
#define MODEM_CHAT_MATCH_WILDCARD(_match, _separators, _callback)
 
#define MODEM_CHAT_MATCH_INITIALIZER(_match, _separators, _callback, _wildcards, _partial)
 
#define MODEM_CHAT_MATCH_DEFINE(_sym, _match, _separators, _callback)
 
#define MODEM_CHAT_MATCHES_DEFINE(_sym, ...)
 
#define MODEM_CHAT_SCRIPT_CMD_RESP(_request, _response_match)
 
#define MODEM_CHAT_SCRIPT_CMD_RESP_MULT(_request, _response_matches)
 
#define MODEM_CHAT_SCRIPT_CMD_RESP_NONE(_request, _timeout_ms)
 
#define MODEM_CHAT_SCRIPT_CMDS_DEFINE(_sym, ...)
 
#define MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, _abort_matches, _callback, _timeout_s)
 
#define MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, _script_chats, _callback, _timeout_s)
 
#define MODEM_CHAT_SCRIPT_EMPTY_DEFINE(_sym)
 

Typedefs

typedef void(* modem_chat_match_callback) (struct modem_chat *chat, char **argv, uint16_t argc, void *user_data)
 Callback called when matching chat is received.
 
typedef void(* modem_chat_script_callback) (struct modem_chat *chat, enum modem_chat_script_result result, void *user_data)
 Callback called when script chat is received.
 

Enumerations

enum  modem_chat_script_result { MODEM_CHAT_SCRIPT_RESULT_SUCCESS , MODEM_CHAT_SCRIPT_RESULT_ABORT , MODEM_CHAT_SCRIPT_RESULT_TIMEOUT }
 
enum  modem_chat_script_send_state { MODEM_CHAT_SCRIPT_SEND_STATE_IDLE , MODEM_CHAT_SCRIPT_SEND_STATE_REQUEST , MODEM_CHAT_SCRIPT_SEND_STATE_DELIMITER }
 

Functions

int modem_chat_init (struct modem_chat *chat, const struct modem_chat_config *config)
 Initialize modem pipe chat instance.
 
int modem_chat_attach (struct modem_chat *chat, struct modem_pipe *pipe)
 Attach modem chat instance to pipe.
 
int modem_chat_run_script_async (struct modem_chat *chat, const struct modem_chat_script *script)
 Run script asynchronously.
 
int modem_chat_run_script (struct modem_chat *chat, const struct modem_chat_script *script)
 Run script.
 
static int modem_chat_script_run (struct modem_chat *chat, const struct modem_chat_script *script)
 Run script asynchronously.
 
void modem_chat_script_abort (struct modem_chat *chat)
 Abort script.
 
void modem_chat_release (struct modem_chat *chat)
 Release pipe from chat instance.
 
void modem_chat_match_init (struct modem_chat_match *chat_match)
 Initialize modem chat match.
 
int modem_chat_match_set_match (struct modem_chat_match *chat_match, const char *match)
 Set match of modem chat match instance.
 
int modem_chat_match_set_separators (struct modem_chat_match *chat_match, const char *separators)
 Set separators of modem chat match instance.
 
void modem_chat_match_set_callback (struct modem_chat_match *chat_match, modem_chat_match_callback callback)
 Set modem chat match callback.
 
void modem_chat_match_set_partial (struct modem_chat_match *chat_match, bool partial)
 Set modem chat match partial flag.
 
void modem_chat_match_enable_wildcards (struct modem_chat_match *chat_match, bool enable)
 Set modem chat match wildcards flag.
 
void modem_chat_script_chat_init (struct modem_chat_script_chat *script_chat)
 Initialize modem chat script chat.
 
int modem_chat_script_chat_set_request (struct modem_chat_script_chat *script_chat, const char *request)
 Set request of modem chat script chat instance.
 
int modem_chat_script_chat_set_response_matches (struct modem_chat_script_chat *script_chat, const struct modem_chat_match *response_matches, uint16_t response_matches_size)
 Set modem chat script chat matches.
 
void modem_chat_script_chat_set_timeout (struct modem_chat_script_chat *script_chat, uint16_t timeout_ms)
 Set modem chat script chat timeout.
 
void modem_chat_script_init (struct modem_chat_script *script)
 Initialize modem chat script.
 
void modem_chat_script_set_name (struct modem_chat_script *script, const char *name)
 Set modem chat script name.
 
int modem_chat_script_set_script_chats (struct modem_chat_script *script, const struct modem_chat_script_chat *script_chats, uint16_t script_chats_size)
 Set modem chat script chats.
 
int modem_chat_script_set_abort_matches (struct modem_chat_script *script, const struct modem_chat_match *abort_matches, uint16_t abort_matches_size)
 Set modem chat script abort matches.
 
void modem_chat_script_set_callback (struct modem_chat_script *script, modem_chat_script_callback callback)
 Set modem chat script callback.
 
void modem_chat_script_set_timeout (struct modem_chat_script *script, uint32_t timeout_s)
 Set modem chat script timeout.
 

Variables

const struct modem_chat_match modem_chat_any_match
 
const struct modem_chat_match modem_chat_empty_matches [0]
 
const struct modem_chat_script_chat modem_chat_empty_script_chats [0]
 

Macro Definition Documentation

◆ MODEM_CHAT_MATCH

#define MODEM_CHAT_MATCH ( _match,
_separators,
_callback )
Value:
{ \
.match = (uint8_t *)(_match), .match_size = (uint8_t)(sizeof(_match) - 1), \
.separators = (uint8_t *)(_separators), \
.separators_size = (uint8_t)(sizeof(_separators) - 1), .wildcards = false, \
.callback = _callback, \
}
__UINT8_TYPE__ uint8_t
Definition stdint.h:88

◆ MODEM_CHAT_MATCH_DEFINE

#define MODEM_CHAT_MATCH_DEFINE ( _sym,
_match,
_separators,
_callback )
Value:
const static struct modem_chat_match _sym = MODEM_CHAT_MATCH(_match, _separators, _callback)
#define MODEM_CHAT_MATCH(_match, _separators, _callback)
Definition chat.h:55
Modem chat match.
Definition chat.h:38

◆ MODEM_CHAT_MATCH_INITIALIZER

#define MODEM_CHAT_MATCH_INITIALIZER ( _match,
_separators,
_callback,
_wildcards,
_partial )
Value:
{ \
.match = (uint8_t *)(_match), \
.match_size = (uint8_t)(sizeof(_match) - 1), \
.separators = (uint8_t *)(_separators), \
.separators_size = (uint8_t)(sizeof(_separators) - 1), \
.wildcards = _wildcards, \
.partial = _partial, \
.callback = _callback, \
}

◆ MODEM_CHAT_MATCH_WILDCARD

#define MODEM_CHAT_MATCH_WILDCARD ( _match,
_separators,
_callback )
Value:
{ \
.match = (uint8_t *)(_match), .match_size = (uint8_t)(sizeof(_match) - 1), \
.separators = (uint8_t *)(_separators), \
.separators_size = (uint8_t)(sizeof(_separators) - 1), .wildcards = true, \
.callback = _callback, \
}

◆ MODEM_CHAT_MATCHES_DEFINE

#define MODEM_CHAT_MATCHES_DEFINE ( _sym,
... )
Value:
const static struct modem_chat_match _sym[] = {__VA_ARGS__}

◆ MODEM_CHAT_SCRIPT_CMD_RESP

#define MODEM_CHAT_SCRIPT_CMD_RESP ( _request,
_response_match )
Value:
{ \
.request = (uint8_t *)(_request), \
.request_size = (uint16_t)(sizeof(_request) - 1), \
.response_matches = &_response_match, \
.response_matches_size = 1, \
.timeout = 0, \
}
__UINT16_TYPE__ uint16_t
Definition stdint.h:89

◆ MODEM_CHAT_SCRIPT_CMD_RESP_MULT

#define MODEM_CHAT_SCRIPT_CMD_RESP_MULT ( _request,
_response_matches )
Value:
{ \
.request = (uint8_t *)(_request), \
.request_size = (uint16_t)(sizeof(_request) - 1), \
.response_matches = _response_matches, \
.response_matches_size = ARRAY_SIZE(_response_matches), \
.timeout = 0, \
}
#define ARRAY_SIZE(array)
Number of elements in the given array.
Definition util.h:127

◆ MODEM_CHAT_SCRIPT_CMD_RESP_NONE

#define MODEM_CHAT_SCRIPT_CMD_RESP_NONE ( _request,
_timeout_ms )
Value:
{ \
.request = (uint8_t *)(_request), \
.request_size = (uint16_t)(sizeof(_request) - 1), \
.response_matches = NULL, \
.response_matches_size = 0, \
.timeout = _timeout_ms, \
}

◆ MODEM_CHAT_SCRIPT_CMDS_DEFINE

#define MODEM_CHAT_SCRIPT_CMDS_DEFINE ( _sym,
... )
Value:
const struct modem_chat_script_chat _sym[] = {__VA_ARGS__}
Modem chat script chat.
Definition chat.h:97

◆ MODEM_CHAT_SCRIPT_DEFINE

#define MODEM_CHAT_SCRIPT_DEFINE ( _sym,
_script_chats,
_abort_matches,
_callback,
_timeout_s )
Value:
const static struct modem_chat_script _sym = { \
.name = #_sym, \
.script_chats = _script_chats, \
.script_chats_size = ARRAY_SIZE(_script_chats), \
.abort_matches = _abort_matches, \
.abort_matches_size = ARRAY_SIZE(_abort_matches), \
.callback = _callback, \
.timeout = _timeout_s, \
}
uint16_t timeout
Timeout before chat script may continue to next step in milliseconds.
Definition chat.h:107
Modem chat script.
Definition chat.h:162
const struct modem_chat_script_chat * script_chats
Array of script chats.
Definition chat.h:166

◆ MODEM_CHAT_SCRIPT_EMPTY_DEFINE

#define MODEM_CHAT_SCRIPT_EMPTY_DEFINE ( _sym)
Value:
const struct modem_chat_script_chat modem_chat_empty_script_chats[0]
#define MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, _script_chats, _callback, _timeout_s)
Definition chat.h:190

◆ MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE

#define MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE ( _sym,
_script_chats,
_callback,
_timeout_s )
Value:
_callback, _timeout_s)
const struct modem_chat_match modem_chat_empty_matches[0]
#define MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, _abort_matches, _callback, _timeout_s)
Definition chat.h:179

Typedef Documentation

◆ modem_chat_match_callback

typedef void(* modem_chat_match_callback) (struct modem_chat *chat, char **argv, uint16_t argc, void *user_data)

Callback called when matching chat is received.

Parameters
chatPointer to chat instance instance
argvPointer to array of parsed arguments
argcNumber of parsed arguments, arg 0 holds the exact match
user_dataFree to use user data set during modem_chat_init()

◆ modem_chat_script_callback

typedef void(* modem_chat_script_callback) (struct modem_chat *chat, enum modem_chat_script_result result, void *user_data)

Callback called when script chat is received.

Parameters
chatPointer to chat instance instance
resultResult of script execution
user_dataFree to use user data set during modem_chat_init()

Enumeration Type Documentation

◆ modem_chat_script_result

Enumerator
MODEM_CHAT_SCRIPT_RESULT_SUCCESS 
MODEM_CHAT_SCRIPT_RESULT_ABORT 
MODEM_CHAT_SCRIPT_RESULT_TIMEOUT 

◆ modem_chat_script_send_state

Enumerator
MODEM_CHAT_SCRIPT_SEND_STATE_IDLE 
MODEM_CHAT_SCRIPT_SEND_STATE_REQUEST 
MODEM_CHAT_SCRIPT_SEND_STATE_DELIMITER 

Function Documentation

◆ modem_chat_attach()

int modem_chat_attach ( struct modem_chat * chat,
struct modem_pipe * pipe )

Attach modem chat instance to pipe.

Parameters
chatChat instance
pipePipe instance to attach Chat instance to
Returns
0 if successful
negative errno code if failure
Note
Chat instance is enabled if successful

◆ modem_chat_init()

int modem_chat_init ( struct modem_chat * chat,
const struct modem_chat_config * config )

Initialize modem pipe chat instance.

Parameters
chatChat instance
configConfiguration which shall be applied to Chat instance
Note
Chat instance must be attached to pipe

◆ modem_chat_match_enable_wildcards()

void modem_chat_match_enable_wildcards ( struct modem_chat_match * chat_match,
bool enable )

Set modem chat match wildcards flag.

Parameters
chat_matchModem chat match instance
enableEnable/disable Wildcards

◆ modem_chat_match_init()

void modem_chat_match_init ( struct modem_chat_match * chat_match)

Initialize modem chat match.

Parameters
chat_matchModem chat match instance

◆ modem_chat_match_set_callback()

void modem_chat_match_set_callback ( struct modem_chat_match * chat_match,
modem_chat_match_callback callback )

Set modem chat match callback.

Parameters
chat_matchModem chat match instance
callbackCallback to set

◆ modem_chat_match_set_match()

int modem_chat_match_set_match ( struct modem_chat_match * chat_match,
const char * match )

Set match of modem chat match instance.

Parameters
chat_matchModem chat match instance
matchMatch to set
Note
The lifetime of match must match or exceed the lifetime of chat_match
Warning
Always call this API after match is modified
Return values
0if successful, negative errno code otherwise

◆ modem_chat_match_set_partial()

void modem_chat_match_set_partial ( struct modem_chat_match * chat_match,
bool partial )

Set modem chat match partial flag.

Parameters
chat_matchModem chat match instance
partialPartial flag to set

◆ modem_chat_match_set_separators()

int modem_chat_match_set_separators ( struct modem_chat_match * chat_match,
const char * separators )

Set separators of modem chat match instance.

Parameters
chat_matchModem chat match instance
separatorsSeparators to set
Note
The lifetime of separators must match or exceed the lifetime of chat_match
Warning
Always call this API after separators are modified
Return values
0if successful, negative errno code otherwise

◆ modem_chat_release()

void modem_chat_release ( struct modem_chat * chat)

Release pipe from chat instance.

Parameters
chatChat instance

◆ modem_chat_run_script()

int modem_chat_run_script ( struct modem_chat * chat,
const struct modem_chat_script * script )

Run script.

Parameters
chatChat instance
scriptScript to run
Returns
0 if successful
-EBUSY if a script is currently running
-EPERM if modem pipe is not attached
-EINVAL if arguments or script is invalid
Note
Script runs until complete or aborted.

◆ modem_chat_run_script_async()

int modem_chat_run_script_async ( struct modem_chat * chat,
const struct modem_chat_script * script )

Run script asynchronously.

Parameters
chatChat instance
scriptScript to run
Returns
0 if script successfully started
-EBUSY if a script is currently running
-EPERM if modem pipe is not attached
-EINVAL if arguments or script is invalid
Note
Script runs asynchronously until complete or aborted.

◆ modem_chat_script_abort()

void modem_chat_script_abort ( struct modem_chat * chat)

Abort script.

Parameters
chatChat instance

◆ modem_chat_script_chat_init()

void modem_chat_script_chat_init ( struct modem_chat_script_chat * script_chat)

Initialize modem chat script chat.

Parameters
script_chatModem chat script chat instance

◆ modem_chat_script_chat_set_request()

int modem_chat_script_chat_set_request ( struct modem_chat_script_chat * script_chat,
const char * request )

Set request of modem chat script chat instance.

Parameters
script_chatModem chat script chat instance
requestRequest to set
Note
The lifetime of request must match or exceed the lifetime of script_chat
Warning
Always call this API after request is modified
Return values
0if successful, negative errno code otherwise

◆ modem_chat_script_chat_set_response_matches()

int modem_chat_script_chat_set_response_matches ( struct modem_chat_script_chat * script_chat,
const struct modem_chat_match * response_matches,
uint16_t response_matches_size )

Set modem chat script chat matches.

Parameters
script_chatModem chat script chat instance
response_matchesResponse match array to set
response_matches_sizeSize of response match array
Note
The lifetime of response_matches must match or exceed the lifetime of script_chat
Return values
0if successful, negative errno code otherwise

◆ modem_chat_script_chat_set_timeout()

void modem_chat_script_chat_set_timeout ( struct modem_chat_script_chat * script_chat,
uint16_t timeout_ms )

Set modem chat script chat timeout.

Parameters
script_chatModem chat script chat instance
timeout_msTimeout in milliseconds

◆ modem_chat_script_init()

void modem_chat_script_init ( struct modem_chat_script * script)

Initialize modem chat script.

Parameters
scriptModem chat script instance

◆ modem_chat_script_run()

static int modem_chat_script_run ( struct modem_chat * chat,
const struct modem_chat_script * script )
inlinestatic

Run script asynchronously.

Note
Function exists for backwards compatibility and should be deprecated
Parameters
chatChat instance
scriptScript to run
Returns
0 if script successfully started
-EBUSY if a script is currently running
-EPERM if modem pipe is not attached
-EINVAL if arguments or script is invalid

◆ modem_chat_script_set_abort_matches()

int modem_chat_script_set_abort_matches ( struct modem_chat_script * script,
const struct modem_chat_match * abort_matches,
uint16_t abort_matches_size )

Set modem chat script abort matches.

Parameters
scriptModem chat script instance
abort_matchesAbort match array to set
abort_matches_sizeSize of abort match array
Note
The lifetime of abort_matches must match or exceed the lifetime of script
Return values
0if successful, negative errno code otherwise

◆ modem_chat_script_set_callback()

void modem_chat_script_set_callback ( struct modem_chat_script * script,
modem_chat_script_callback callback )

Set modem chat script callback.

Parameters
scriptModem chat script instance
callbackCallback to set

◆ modem_chat_script_set_name()

void modem_chat_script_set_name ( struct modem_chat_script * script,
const char * name )

Set modem chat script name.

Parameters
scriptModem chat script instance
nameName to set
Note
The lifetime of name must match or exceed the lifetime of script

◆ modem_chat_script_set_script_chats()

int modem_chat_script_set_script_chats ( struct modem_chat_script * script,
const struct modem_chat_script_chat * script_chats,
uint16_t script_chats_size )

Set modem chat script chats.

Parameters
scriptModem chat script instance
script_chatsChat script array to set
script_chats_sizeSize of chat script array
Note
The lifetime of script_chats must match or exceed the lifetime of script
Return values
0if successful, negative errno code otherwise

◆ modem_chat_script_set_timeout()

void modem_chat_script_set_timeout ( struct modem_chat_script * script,
uint32_t timeout_s )

Set modem chat script timeout.

Parameters
scriptModem chat script instance
timeout_sTimeout in seconds

Variable Documentation

◆ modem_chat_any_match

const struct modem_chat_match modem_chat_any_match
extern

◆ modem_chat_empty_matches

const struct modem_chat_match modem_chat_empty_matches[0]
extern

◆ modem_chat_empty_script_chats

const struct modem_chat_script_chat modem_chat_empty_script_chats[0]
extern