Modem Chat

Modem Chat. More...

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_MATCH_WILDCARD_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 }

Functions
static uint16_t	modem_chat_callback_script_chat_index (const struct modem_chat *chat)
	Get the modem chat script command index at callback time.
static const struct modem_chat_script_chat *	modem_chat_callback_script_chat (const struct modem_chat *chat)
	Get the modem chat script command that was active at callback time.
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.
bool	modem_chat_is_running (struct modem_chat *chat)
	Check if a script is running.
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]

Detailed Description

Modem Chat.

Since

3.5

Version

1.0.0

Macro Definition Documentation

MODEM_CHAT_MATCH

#define MODEM_CHAT_MATCH	(		_match,
			_separators,
			_callback )

#include <chat.h>

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,                                                             \
}

MODEM_CHAT_MATCH_DEFINE

#define MODEM_CHAT_MATCH_DEFINE	(		_sym,
			_match,
			_separators,
			_callback )

#include <chat.h>

Value:

const static struct modem_chat_match _sym = MODEM_CHAT_MATCH(_match, _separators, _callback)

MODEM_CHAT_MATCH_INITIALIZER

#define MODEM_CHAT_MATCH_INITIALIZER	(		_match,
			_separators,
			_callback,
			_wildcards,
			_partial )

#include <chat.h>

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 )

#include <chat.h>

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_MATCH_WILDCARD_DEFINE

#define MODEM_CHAT_MATCH_WILDCARD_DEFINE	(		_sym,
			_match,
			_separators,
			_callback )

#include <chat.h>

Value:

const static struct modem_chat_match _sym =                                                \
        MODEM_CHAT_MATCH_WILDCARD(_match, _separators, _callback)

MODEM_CHAT_MATCHES_DEFINE

#define MODEM_CHAT_MATCHES_DEFINE	(		_sym,
			... )

#include <chat.h>

Value:

const static struct modem_chat_match _sym[] = {__VA_ARGS__}

MODEM_CHAT_SCRIPT_CMD_RESP

#define MODEM_CHAT_SCRIPT_CMD_RESP	(		_request,
			_response_match )

#include <chat.h>

Value:

{                                                                                          \
        .request = (uint8_t *)(_request),                                                  \
        .request_size = (uint16_t)(sizeof(_request) - 1),                                  \
        .response_matches = &_response_match,                                              \
        .response_matches_size = 1,                                                        \
        .timeout = 0,                                                                      \
}

MODEM_CHAT_SCRIPT_CMD_RESP_MULT

#define MODEM_CHAT_SCRIPT_CMD_RESP_MULT	(		_request,
			_response_matches )

#include <chat.h>

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,                                                                      \
}

MODEM_CHAT_SCRIPT_CMD_RESP_NONE

#define MODEM_CHAT_SCRIPT_CMD_RESP_NONE	(		_request,
			_timeout_ms )

#include <chat.h>

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,
			... )

#include <chat.h>

Value:

const static struct modem_chat_script_chat _sym[] = {__VA_ARGS__}

MODEM_CHAT_SCRIPT_DEFINE

#define MODEM_CHAT_SCRIPT_DEFINE	(		_sym,
			_script_chats,
			_abort_matches,
			_callback,
			_timeout_s )

#include <chat.h>

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,                                                             \
}

MODEM_CHAT_SCRIPT_EMPTY_DEFINE

#define MODEM_CHAT_SCRIPT_EMPTY_DEFINE

(

_sym

)

#include <chat.h>

Value:

MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, modem_chat_empty_script_chats, NULL, 0)

MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE

#define MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE	(		_sym,
			_script_chats,
			_callback,
			_timeout_s )

#include <chat.h>

Value:

MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, modem_chat_empty_matches,                    \
                         _callback, _timeout_s)

Typedef Documentation

modem_chat_match_callback

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

#include <chat.h>

Callback called when matching chat is received.

Parameters

chat	Pointer to chat instance instance
argv	Pointer to array of parsed arguments
argc	Number of parsed arguments, arg 0 holds the exact match
user_data	Free 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)

#include <chat.h>

Callback called when script chat is received.

Parameters

chat	Pointer to chat instance instance
result	Result of script execution
user_data	Free to use user data set during modem_chat_init()

Enumeration Type Documentation

modem_chat_script_result

enum modem_chat_script_result

#include <chat.h>

Enumerator
MODEM_CHAT_SCRIPT_RESULT_SUCCESS
MODEM_CHAT_SCRIPT_RESULT_ABORT
MODEM_CHAT_SCRIPT_RESULT_TIMEOUT

modem_chat_script_send_state

enum modem_chat_script_send_state

#include <chat.h>

Enumerator
MODEM_CHAT_SCRIPT_SEND_STATE_IDLE
MODEM_CHAT_SCRIPT_SEND_STATE_REQUEST

Function Documentation

modem_chat_attach()

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

#include <chat.h>

Attach modem chat instance to pipe.

Parameters

chat	Chat instance
pipe	Pipe instance to attach Chat instance to

Returns

0 if successful

negative errno code if failure

Note

Chat instance is enabled if successful

modem_chat_callback_script_chat()

const struct modem_chat_script_chat * modem_chat_callback_script_chat ( const struct modem_chat * chat )

inlinestatic

#include <chat.h>

Get the modem chat script command that was active at callback time.

Warning

This function must only be called from the modem chat script callback. The modem chat instance may execute in a different context from other callers, making access to the script execution state unsafe outside the callback.

The returned pointer is guaranteed to remain valid only for the duration of the callback. The caller must not retain or dereference the pointer after the callback returns. Outside the callback, only the owner of the script and its command array can determine their lifetime.

When the script completes successfully, there is no current command and this function returns NULL.

Parameters

chat	Non-NULL modem chat instance associated with the callback.

Returns

Pointer to the script command that was active when the callback was invoked.

Return values

NULL	if no current script command is available.

modem_chat_callback_script_chat_index()

uint16_t modem_chat_callback_script_chat_index ( const struct modem_chat * chat )

inlinestatic

#include <chat.h>

Get the modem chat script command index at callback time.

Warning

This function must only be called from the modem chat script callback. The modem chat instance may execute in a different context from other callers, making access to the script execution state unsafe outside the callback.

When called after a script completes successfully, the returned index is equal to the number of commands in the script and does not identify a valid command.

Parameters

chat	Non-NULL modem chat instance associated with the callback.

Returns

Script command index at callback time.

modem_chat_init()

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

#include <chat.h>

Initialize modem pipe chat instance.

Parameters

chat	Chat instance
config	Configuration which shall be applied to Chat instance

Note

Chat instance must be attached to pipe

modem_chat_is_running()

bool modem_chat_is_running

(

struct modem_chat *

chat

)

#include <chat.h>

Check if a script is running.

Parameters

chat	Chat instance

Returns

true if a script is currently running

false if a script is not currently running

modem_chat_match_enable_wildcards()

void modem_chat_match_enable_wildcards	(	struct modem_chat_match *	chat_match,
		bool	enable )

#include <chat.h>

Set modem chat match wildcards flag.

Parameters

chat_match	Modem chat match instance
enable	Enable/disable Wildcards

modem_chat_match_init()

void modem_chat_match_init

(

struct modem_chat_match *

chat_match

)

#include <chat.h>

Initialize modem chat match.

Parameters

chat_match

Modem 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 )

#include <chat.h>

Set modem chat match callback.

Parameters

chat_match	Modem chat match instance
callback	Callback to set

modem_chat_match_set_match()

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

#include <chat.h>

Set match of modem chat match instance.

Parameters

chat_match	Modem chat match instance
match	Match 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

0	if successful, negative errno code otherwise

modem_chat_match_set_partial()

void modem_chat_match_set_partial	(	struct modem_chat_match *	chat_match,
		bool	partial )

#include <chat.h>

Set modem chat match partial flag.

Parameters

chat_match	Modem chat match instance
partial	Partial flag to set

modem_chat_match_set_separators()

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

#include <chat.h>

Set separators of modem chat match instance.

Parameters

chat_match	Modem chat match instance
separators	Separators 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

0	if successful, negative errno code otherwise

modem_chat_release()

void modem_chat_release

(

struct modem_chat *

chat

)

#include <chat.h>

Release pipe from chat instance.

Parameters

chat	Chat instance

modem_chat_run_script()

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

#include <chat.h>

Run script.

Parameters

chat	Chat instance
script	Script 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 )

#include <chat.h>

Run script asynchronously.

Parameters

chat	Chat instance
script	Script 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

)

#include <chat.h>

Abort script.

Parameters

chat	Chat instance

modem_chat_script_chat_init()

void modem_chat_script_chat_init

(

struct modem_chat_script_chat *

script_chat

)

#include <chat.h>

Initialize modem chat script chat.

Parameters

script_chat

Modem 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 )

#include <chat.h>

Set request of modem chat script chat instance.

Parameters

script_chat	Modem chat script chat instance
request	Request 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

0	if 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 )

#include <chat.h>

Set modem chat script chat matches.

Parameters

script_chat	Modem chat script chat instance
response_matches	Response match array to set
response_matches_size	Size of response match array

Note

The lifetime of response_matches must match or exceed the lifetime of script_chat

Return values

0	if 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 )

#include <chat.h>

Set modem chat script chat timeout.

Parameters

script_chat	Modem chat script chat instance
timeout_ms	Timeout in milliseconds

modem_chat_script_init()

void modem_chat_script_init

(

struct modem_chat_script *

script

)

#include <chat.h>

Initialize modem chat script.

Parameters

script

Modem chat script instance

modem_chat_script_run()

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

inlinestatic

#include <chat.h>

Run script asynchronously.

Note

Function exists for backwards compatibility and should be deprecated

Parameters

chat	Chat instance
script	Script 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 )

#include <chat.h>

Set modem chat script abort matches.

Parameters

script	Modem chat script instance
abort_matches	Abort match array to set
abort_matches_size	Size of abort match array

Note

The lifetime of abort_matches must match or exceed the lifetime of script

Return values

0	if 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 )

#include <chat.h>

Set modem chat script callback.

Parameters

script	Modem chat script instance
callback	Callback to set

modem_chat_script_set_name()

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

#include <chat.h>

Set modem chat script name.

Parameters

script	Modem chat script instance
name	Name 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 )

#include <chat.h>

Set modem chat script chats.

Parameters

script	Modem chat script instance
script_chats	Chat script array to set
script_chats_size	Size of chat script array

Note

The lifetime of script_chats must match or exceed the lifetime of script

Return values

0	if 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 )

#include <chat.h>

Set modem chat script timeout.

Parameters

script	Modem chat script instance
timeout_s	Timeout in seconds

Variable Documentation

modem_chat_any_match

const struct modem_chat_match modem_chat_any_match

extern

#include <chat.h>

modem_chat_empty_matches

const struct modem_chat_match modem_chat_empty_matches[0]

extern

#include <chat.h>

modem_chat_empty_script_chats

const struct modem_chat_script_chat modem_chat_empty_script_chats[0]

extern

#include <chat.h>