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>

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)    const static struct modem_chat_match _sym = MODEM_CHAT_MATCH(_match, _separators, _callback)
#define	MODEM_CHAT_MATCHES_DEFINE(_sym, ...)    const static struct modem_chat_match _sym[] = {__VA_ARGS__}
#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, ...)    const struct modem_chat_script_chat _sym[] = {__VA_ARGS__}
#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)    MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, modem_chat_empty_script_chats, NULL, 0)

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.

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

MODEM_CHAT_MATCH_DEFINE

#define MODEM_CHAT_MATCH_DEFINE	(		_sym,
			_match,
			_separators,
			_callback
	)		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
	)

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

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

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

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

)

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
	)

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)

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)

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

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

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

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_init()

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

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_release()

void modem_chat_release

(

struct modem_chat *

chat

)

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
	)

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
	)

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

)

Abort script.

Parameters

chat	Chat 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

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

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