axa 3.0.2
Farsight Security Advanced Exchange Access (AXA)
axa_client

Detailed Description

axa_client contains AXA client macros, data type definitions, and function prototypes.

Data Structures

struct  axa_client_t
 AXA client state. More...
 

Macros

#define AXA_MAX_SRVRLEN   (4+64+1025+1)
 maximum length of an AXA server specification such as "unix user@host"
 
#define AXA_CLIENT_OPENED(client)   AXA_IO_OPENED(&((client)->io))
 Check than an AXA client context is closed.
 
#define AXA_CLIENT_CONNECTED(client)   AXA_IO_CONNECTED(&((client)->io))
 Check that an AXA client context is open and connected.
 

Enumerations

enum  axa_connect_result_t
 return codes for axa_client_open() and axa_client_connect() More...
 

Functions

void axa_client_init (axa_client_t *client)
 (Re-)initialize an AXA client context with default values.
 
void axa_client_backoff (axa_client_t *client)
 Disconnect from the server and increase the delay before trying again.
 
void axa_client_backoff_max (axa_client_t *client)
 Disconnect from the server and increase the delay before trying again to the maximum.
 
void axa_client_backoff_reset (axa_client_t *client)
 Reset the delay before try to connect to zero.
 
time_t axa_client_again (axa_client_t *client, struct timeval *now)
 Get the number of milliseconds before the server connection should be attempted again.
 
void axa_client_close (axa_client_t *client)
 Close the server connection and release buffers.
 
axa_connect_result_t axa_client_open (axa_emsg_t *emsg, axa_client_t *client, const char *addr, bool is_rad, int bufsize, bool nonblock)
 Create a new server connection perhaps after closing an existing connection.
 
axa_connect_result_t axa_client_connect (axa_emsg_t *emsg, axa_client_t *client)
 Finish a new connection to an SRA or RAD server.
 
bool axa_client_send (axa_emsg_t *emsg, axa_client_t *client, axa_tag_t tag, axa_p_op_t op, axa_p_hdr_t *hdr, const void *body, size_t body_len)
 Send an AXA message to the server connected through a client context, blocking until finished.
 
bool axa_client_get_hello_string (axa_emsg_t *emsg, const char *origin, axa_client_t *client, char **out)
 Retrieve a detailed string describing the local host/config to pass to the AXA server as part of a client HELLO message.
 
bool axa_client_hello (axa_emsg_t *emsg, axa_client_t *client, const axa_p_hello_t *hello, const char *origin)
 Examine HELLO message from server to pick a common protocol version and save session information.
 

Macro Definition Documentation

◆ AXA_MAX_SRVRLEN

#define AXA_MAX_SRVRLEN   (4+64+1025+1)

maximum length of an AXA server specification such as "unix user@host"

◆ AXA_CLIENT_OPENED

#define AXA_CLIENT_OPENED (   client)    AXA_IO_OPENED(&((client)->io))

Check than an AXA client context is closed.

Parameters
[in]clientaddress of a client context

◆ AXA_CLIENT_CONNECTED

#define AXA_CLIENT_CONNECTED (   client)    AXA_IO_CONNECTED(&((client)->io))

Check that an AXA client context is open and connected.

Parameters
[in]clientaddress of a client context

Enumeration Type Documentation

◆ axa_connect_result_t

return codes for axa_client_open() and axa_client_connect()

Enumerator
AXA_CONNECT_ERR 

Permanent failure.

The connection has been closed and axa_client_backoff() called. Check emsg.

AXA_CONNECT_TEMP 

Temporary failure.

The connection has been closed and axa_client_backoff() called. Check emsg

AXA_CONNECT_DONE 

connection is complete

AXA_CONNECT_INCOM 

non-blocking connection waiting for TCP syn-ack or TLS handshake

AXA_CONNECT_NOP 

Connection now completed including sending the initial AXA_P_OP_NOP.

emsg contains the result of axa_p_to_str(emsg->c, sizeof(emsg->c), true, ...)

AXA_CONNECT_USER 

Connection now completed including sending the initial AXA_P_OP_USER.

An AXA_P_OP_OK or AXA_P_OP_ERROR should be coming. emsg contains the result of axa_p_to_str(emsg->c, sizeof(emsg->c), true, ...)

Function Documentation

◆ axa_client_init()

void axa_client_init ( axa_client_t client)

(Re-)initialize an AXA client context with default values.

Parameters
[in]clientaddress of a client context

◆ axa_client_backoff()

void axa_client_backoff ( axa_client_t client)

Disconnect from the server and increase the delay before trying again.

Parameters
[in]clientaddress of a client context

◆ axa_client_backoff_max()

void axa_client_backoff_max ( axa_client_t client)

Disconnect from the server and increase the delay before trying again to the maximum.

Parameters
[in]clientaddress of a client context

◆ axa_client_backoff_reset()

void axa_client_backoff_reset ( axa_client_t client)

Reset the delay before try to connect to zero.

Parameters
[in]clientaddress of a client context

◆ axa_client_again()

time_t axa_client_again ( axa_client_t client,
struct timeval *  now 
)

Get the number of milliseconds before the server connection should be attempted again.

Parameters
[in]clientaddress of a client context
[out]nowcurrent wall clock time or NULL
Returns
<= 0 if yes

◆ axa_client_close()

void axa_client_close ( axa_client_t client)

Close the server connection and release buffers.

Parameters
[in]clientaddress of a client context

◆ axa_client_open()

axa_connect_result_t axa_client_open ( axa_emsg_t emsg,
axa_client_t client,
const char *  addr,
bool  is_rad,
int  bufsize,
bool  nonblock 
)

Create a new server connection perhaps after closing an existing connection.

axa_client_connect() must be called after a result other than AXA_CONNECT_DONE, AXA_CONNECT_NOP, or AXA_CONNECT_USER.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]clientaddress of a client context
[in]is_radtrue if server is radd instead of srad
[in]addrconnect to this AXA server specification
[in]bufsize0 or desired socket buffer sizes
[in]nonblocktrue to start the connection without blocking and to make the connection non-blocking
Return values
oneof axa_connect_result_t

◆ axa_client_connect()

axa_connect_result_t axa_client_connect ( axa_emsg_t emsg,
axa_client_t client 
)

Finish a new connection to an SRA or RAD server.

The connection must have been previously opened with axa_client_open(), which must have returned AXA_CONNECT_TEMP. axa_client_connect() must be called again when it returns AXA_CONNECT_TEMP.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]clientaddress of a client context
Return values
oneof axa_connect_result_t

◆ axa_client_send()

bool axa_client_send ( axa_emsg_t emsg,
axa_client_t client,
axa_tag_t  tag,
axa_p_op_t  op,
axa_p_hdr_t hdr,
const void *  body,
size_t  body_len 
)

Send an AXA message to the server connected through a client context, blocking until finished.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]clientaddress of a client context
[in]tagAXA tag
[in]opAXA opcode
[out]hdrAXA protocol header to be built or NULL
[in]bodyNULL or optional body of the AXA message after the header
[in]body_lenlength of body
Return values
truesuccess
falseerror. Call axa_client_backoff() and check check emsg.

◆ axa_client_get_hello_string()

bool axa_client_get_hello_string ( axa_emsg_t emsg,
const char *  origin,
axa_client_t client,
char **  out 
)

Retrieve a detailed string describing the local host/config to pass to the AXA server as part of a client HELLO message.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]originnull-terminated string containing the name of the requesting client application or service, i.e. radtool, sratunnel, etc.
[in]clientaddress of the client context
[out]outpointer to a char * that is assigned on success. Must be freed by caller.
Return values
trueversion string was generated successfully
falseerror occurred making client HELLO string

◆ axa_client_hello()

bool axa_client_hello ( axa_emsg_t emsg,
axa_client_t client,
const axa_p_hello_t hello,
const char *  origin 
)

Examine HELLO message from server to pick a common protocol version and save session information.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]clientaddress of the client context default to &client->recv_body->hello if NULL
[in]helloaddress of the received HELLO message or NULL, which implies client->recv_body->hello
[in]originnull-terminated string with name of requesting application, which will be sent back in a client HELLO string
Return values
trueparameters saved
falsebad HELLO