Bus Connections

Functions
int	amxb_connect (amxb_bus_ctx_t **ctx, const char *uri)
	Create a bus connection. More...
int	amxb_connect_intf (amxb_bus_ctx_t **ctx, const char *uri, const char *intf)
	Create a bus connection. More...
int	amxb_listen (amxb_bus_ctx_t **ctx, const char *uri)
	Create a listen socket. More...
int	amxb_accept (amxb_bus_ctx_t *listen_ctx, amxb_bus_ctx_t **accepted_ctx)
	Accepts an incomming connection request. More...
int	amxb_disconnect (amxb_bus_ctx_t *ctx)
	Disconnects a bus connection. More...
void	amxb_free (amxb_bus_ctx_t **ctx)
	Frees allocated memory. More...
amxb_bus_ctx_t *	amxb_find_uri (const char *uri)
	Find the bus context for a given uri. More...
amxc_array_t *	amxb_list_uris (void)
	List all open connections by their uri. More...
int	amxb_get_fd (const amxb_bus_ctx_t *const ctx)
	Get the connection file descriptor. More...
int	amxb_read (const amxb_bus_ctx_t *const ctx)
	Reads data from the file descriptor. More...
int	amxb_read_raw (const amxb_bus_ctx_t *const ctx, void *buf, size_t count)
	Attempts to read up to count bytes from the file descriptor into the buffer starting at buf. More...
static void	amxb_set_access (amxb_bus_ctx_t *const ctx, uint32_t access)
	Sets the access method. More...
static bool	amxb_is_listen_socket (const amxb_bus_ctx_t *const ctx)
	Checks if the provided context is a listen socket. More...
static bool	amxb_is_data_socket (const amxb_bus_ctx_t *const ctx)
	Checks if the provided context is a data socket. More...

Detailed Description

Function Documentation

amxb_accept()

int amxb_accept	(	amxb_bus_ctx_t *	listen_ctx,
		amxb_bus_ctx_t **	accepted_ctx
	)

Accepts an incomming connection request.

To be able to accept incoming connection requests a listen socket must be created first. A listen socket can be created using amxb_listen.

This function is typically used from within an event loop callback function, and should be called when data is available on the created listen socket.

Note

This function allocates memory for the new connection context. The connection context can be freed using amxb_free

Parameters

listen_ctx	The listen connection context
accepted_ctx	The accepted connection

Returns

• AMXB_STATUS_OK when connection is created
• AMXB_ERROR_INVALID_URI when invalid URI was passed
• AMXB_ERROR_NOT_SUPPORTED_SCHEME when no matching backend was found
• AMXB_ERROR_BACKEND_FAILED when backend failed to connect to the bus
• AMXB_ERROR_NOT_SUPPORTED_OP when backend does not support connect operation
• AMXB_ERROR_UNKNOWN when invalid arguments are passed or when failed to allocate memory

Definition at line 268 of file amxb_ba_connect.c.

                                                                           {
    int retval = -1;
    amxb_be_funcs_t* fns = NULL;
    const char* uri = NULL;
    char* scheme = NULL;
    char* host = NULL;
    char* port = NULL;
    char* path = NULL;
 
    when_null(listen_ctx, exit);
    uri = amxc_htable_it_get_key(&listen_ctx->hit);
    when_null(listen_ctx, exit);
    retval = amxb_bus_ctx_create(accepted_ctx, &fns, uri, &scheme, &host, &port, &path);
    when_failed(retval, exit);
    if(amxb_is_valid_be_func(fns, accept, fns->accept)) {
        (*accepted_ctx)->bus_ctx = fns->accept(listen_ctx->bus_ctx, &listen_ctx->sigmngr);
        if((*accepted_ctx)->bus_ctx == NULL) {
            retval = AMXB_ERROR_BACKEND_FAILED;
        } else {
            (*accepted_ctx)->dm = listen_ctx->dm;
            amxc_llist_append(&fns->connections, &(*accepted_ctx)->it);
            retval = 0;
        }
    } else {
        retval = AMXB_ERROR_NOT_SUPPORTED_OP;
    }
 
exit:
    free(scheme);
    free(port);
    free(host);
    free(path);
    return retval;
}

amxb_connect()

int amxb_connect	(	amxb_bus_ctx_t **	ctx,
		const char *	uri
	)

Create a bus connection.

Connects to a bus using a uri.

The uri must be strictly compliant with RFC 3986. The scheme of the uri refers to the backend that is used. The other parts of the uri are used by the backend to create a connection

Searches a bus backend using the scheme of the uri, if found creates a connection to the bus and allocates a connection context.

Multiple connections can be created to different busses.

Note

This function allocates memory for the connection context. The connection context can be freed using amxb_free

Parameters

ctx	The connection context
uri	The connection uri, compliant with RFC 3986

Returns

• AMXB_STATUS_OK when connection is created
• AMXB_ERROR_INVALID_URI when invalid URI was passed
• AMXB_ERROR_NOT_SUPPORTED_SCHEME when no matching backend was found
• AMXB_ERROR_BACKEND_FAILED when backend failed to connect to the bus
• AMXB_ERROR_NOT_SUPPORTED_OP when backend does not support connect operation
• AMXB_ERROR_UNKNOWN when invalid arguments are passed or when failed to allocate memory

Definition at line 235 of file amxb_ba_connect.c.

                                                        {
    return amxb_connect_intf(ctx, uri, NULL);
}

amxb_connect_intf()

int amxb_connect_intf	(	amxb_bus_ctx_t **	ctx,
		const char *	uri,
		const char *	intf
	)

Create a bus connection.

Connects to a bus using a uri and a network interface name or id (aka zone id).

This function works exactly the same as Bus Connections, the interface name will be added to the host part of the uri prefixed with a %.

Parameters

ctx	The connection context
uri	The connection uri, compliant with RFC 3986

Returns

• AMXB_STATUS_OK when connection is created
• AMXB_ERROR_INVALID_URI when invalid URI was passed
• AMXB_ERROR_NOT_SUPPORTED_SCHEME when no matching backend was found
• AMXB_ERROR_BACKEND_FAILED when backend failed to connect to the bus
• AMXB_ERROR_NOT_SUPPORTED_OP when backend does not support connect operation
• AMXB_ERROR_UNKNOWN when invalid arguments are passed or when failed to allocate memory

Definition at line 197 of file amxb_ba_connect.c.

                                                                               {
    int retval = -1;
    amxb_be_funcs_t* fns = NULL;
    char* scheme = NULL;
    char* host = NULL;
    char* port = NULL;
    char* path = NULL;
 
    retval = amxb_bus_ctx_create(ctx, &fns, uri, &scheme, &host, &port, &path);
    when_failed(retval, exit);
    if((host != NULL) && (*host != 0) && (intf != NULL) && (*intf != 0)) {
        // add the interface name/index prefixed with % to the host.
        amxc_string_t host_intf;
        amxc_string_init(&host_intf, 64);
        amxc_string_setf(&host_intf, "%s%%%s", host, intf);
        free(host);
        host = amxc_string_take_buffer(&host_intf);
        amxc_string_clean(&host_intf);
    }
 
    if(amxb_is_valid_be_func(fns, connect, fns->connect)) {
        retval = amxb_bus_ctx_be_init(*ctx, fns, fns->connect, uri, host, port, path);
    } else {
        retval = AMXB_ERROR_NOT_SUPPORTED_OP;
    }
 
    if(retval != 0) {
        amxb_free(ctx);
    }
 
exit:
    free(scheme);
    free(port);
    free(host);
    free(path);
    return retval;
}

amxb_disconnect()

int amxb_disconnect

(

amxb_bus_ctx_t *

ctx

)

Disconnects a bus connection.

Closes the connection to a bus that was previously created with Bus Connections.

After calling this function the connection is closed and can not be used any more.

Note

This functions does not free the allocated memory for the connection context.

Parameters

ctx	the connection context

Returns

• AMXB_STATUS_OK when connection is disconnected
• AMXB_ERROR_NOT_SUPPORTED_OP backend does not support disconnect operation
• AMXB_ERROR_UNKNOWN invalid arguments are passed

Definition at line 303 of file amxb_ba_connect.c.

                                         {
    int retval = -1;
    const amxb_be_funcs_t* fns = NULL;
 
    when_null(ctx, exit);
    when_null(ctx->bus_ctx, exit_clean);
 
    amxb_be_cache_remove_ctx(ctx);
 
    amxc_llist_for_each(it, &ctx->client_subs) {
        amxb_sub_t* sub = amxc_container_of(it, amxb_sub_t, it);
        amxb_subscription_remove(&sub->data);
    }
 
    fns = ctx->bus_fn;
    if(amxb_is_valid_be_func(fns, disconnect, fns->disconnect)) {
        retval = fns->disconnect(ctx->bus_ctx);
    } else {
        retval = AMXB_ERROR_NOT_SUPPORTED_OP;
    }
 
    if(fns->free != NULL) {
        fns->free(ctx->bus_ctx);
    }
 
exit_clean:
    amxc_llist_clean(&ctx->requests, amxb_free_request);
    amxc_llist_clean(&ctx->invoke_ctxs, NULL);
    amxc_llist_it_take(&ctx->it);
    amxc_htable_it_clean(&ctx->hit, NULL);
    ctx->bus_ctx = NULL;
    ctx->bus_fn = NULL;
exit:
    return retval;
}

amxb_find_uri()

amxb_bus_ctx_t* amxb_find_uri

(

const char *

uri

)

Find the bus context for a given uri.

If a connection already exists for a uri, the bus_ctx can be retrieved using this function

Parameters

uri	The connection uri

Returns

the bus context if any exists for the given uri, NULL otherwise.

Definition at line 360 of file amxb_ba_connect.c.

                                               {
    amxc_htable_it_t* hit = amxc_htable_get(&uri_bus_ctxs, uri);
    amxb_bus_ctx_t* ctx = NULL;
 
    if(hit != NULL) {
        ctx = amxc_htable_it_get_data(hit, amxb_bus_ctx_t, hit);
    }
    return ctx;
}

amxb_free()

void amxb_free

(

amxb_bus_ctx_t **

ctx

)

Frees allocated memory.

The allocated memory for the connection context is freed.

The connection is automatically disconnected if it is still connected.

The pointer to the connection context is reset to NULL

Parameters

ctx	the connection context that was created with Bus Connections

Definition at line 339 of file amxb_ba_connect.c.

                                     {
    when_null(ctx, exit);
    when_null(*ctx, exit);
 
    amxb_disconnect(*ctx);
    amxp_sigmngr_clean(&(*ctx)->sigmngr);
 
    amxc_htable_for_each(it, &(*ctx)->subscriptions) {
        amxp_slot_disconnect_with_priv(&(*ctx)->dm->sigmngr, amxb_dm_event_to_object_event, it);
        amxc_htable_it_clean(it, NULL);
        free(it);
    }
    amxc_htable_clean(&(*ctx)->subscriptions, NULL);
 
    free(*ctx);
    *ctx = NULL;
 
exit:
    return;
}

amxb_get_fd()

int amxb_get_fd

(

const amxb_bus_ctx_t *const

ctx

)

Get the connection file descriptor.

Gets the file descriptor of the connection context. Use this function to add the file descriptor to your event loop.

Parameters

ctx	the connection context

Returns

The valid file descriptor or -1 when no file descriptor is available.

Definition at line 375 of file amxb_ba_connect.c.

                                                 {
    int retval = -1;
    const amxb_be_funcs_t* fns = NULL;
 
    when_null(ctx, exit);
    when_null(ctx->bus_ctx, exit);
 
    fns = ctx->bus_fn;
    if(amxb_is_valid_be_func(fns, get_fd, fns->get_fd)) {
        retval = fns->get_fd(ctx->bus_ctx);
        when_true(retval < 0, exit);
    }
 
exit:
    return retval;
}

amxb_is_data_socket()

static bool amxb_is_data_socket ( const amxb_bus_ctx_t *const  ctx )

inlinestatic

Checks if the provided context is a data socket.

Data sockets are used to transfer messages between applications.

Parameters

ctx	the connection context

Returns

true when the provided connection context is a data socket, false otherwise

Definition at line 397 of file amxb_connect.h.

                                                          {
    return ctx == NULL ? false : ctx->socket_type == AMXB_DATA_SOCK;
}

amxb_is_listen_socket()

static bool amxb_is_listen_socket ( const amxb_bus_ctx_t *const  ctx )

inlinestatic

Checks if the provided context is a listen socket.

With a listen socket connection, incoming connection requests can be handled. Using listen sockets it is possible to create an E2E connection between different applications, without the need for a broker/dispatcher process.

Depending on the back-end and bus system used, this feature may not be available.

Parameters

ctx	the connection context

Returns

true when the provided connection context is a listen socket, false otherwise

Definition at line 379 of file amxb_connect.h.

                                                            {
    return ctx == NULL ? false : ctx->socket_type == AMXB_LISTEN_SOCK;
}

amxb_list_uris()

amxc_array_t* amxb_list_uris

(

void

)

List all open connections by their uri.

returns an amxc_array_t containing const char * of all connect uris.

Note

The returned array contains const char*, the content should not be deleted The returned amxc_array_t* must be deleted using amxc_array_delete function.

Returns

A pointer to an amxc_array_t, which must be freed using amxc_array_delete Do not free the content of the array.

Definition at line 370 of file amxb_ba_connect.c.

                                   {
    amxc_array_t* keys = amxc_htable_get_sorted_keys(&uri_bus_ctxs);
    return keys;
}

amxb_listen()

int amxb_listen	(	amxb_bus_ctx_t **	ctx,
		const char *	uri
	)

Create a listen socket.

Creates a listen socket using a specific back-end.

The uri must be strictly compliant with RFC 3986. The scheme of the uri refers to the backend that is used. The other parts of the uri are used by the backend to create a connection

Searches a bus backend using the scheme of the uri, if found and the back-end supports the creation of a listen socket, a listen socket is created.

Multiple listen sockets can be created using different back-ends.

When a listen socket is created, its file descriptor should be added to the event loop, when data is available on that file descriptor (incoming connection), the callback function in the event loop should call amxb_accept

Note

This function allocates memory for the connection context. The connection context can be freed using amxb_free

Not all bus systems or back-ends support the creation of a listen socket. Consult the documentation of the back-end or the specific bus system to verify that listen sockets are supported.

Parameters

ctx	The connection context
uri	The listen uri, compliant with RFC 3986

Returns

• AMXB_STATUS_OK when connection is created
• AMXB_ERROR_INVALID_URI when invalid URI was passed
• AMXB_ERROR_NOT_SUPPORTED_SCHEME when no matching backend was found
• AMXB_ERROR_BACKEND_FAILED when backend failed to connect to the bus
• AMXB_ERROR_NOT_SUPPORTED_OP when backend does not support connect operation
• AMXB_ERROR_UNKNOWN when invalid arguments are passed or when failed to allocate memory

Definition at line 239 of file amxb_ba_connect.c.

                                                       {
    int retval = -1;
    amxb_be_funcs_t* fns = NULL;
    char* scheme = NULL;
    char* host = NULL;
    char* port = NULL;
    char* path = NULL;
 
    retval = amxb_bus_ctx_create(ctx, &fns, uri, &scheme, &host, &port, &path);
    when_failed(retval, exit);
    (*ctx)->socket_type = AMXB_LISTEN_SOCK;
    if(amxb_is_valid_be_func(fns, listen, fns->listen)) {
        retval = amxb_bus_ctx_be_init(*ctx, fns, fns->listen, uri, host, port, path);
    } else {
        retval = AMXB_ERROR_NOT_SUPPORTED_OP;
    }
 
    if(retval != 0) {
        amxb_free(ctx);
    }
 
exit:
    free(scheme);
    free(port);
    free(host);
    free(path);
    return retval;
}

amxb_read()

int amxb_read

(

const amxb_bus_ctx_t *const

ctx

)

Reads data from the file descriptor.

Reads data from the file descriptor of the connection context.

Typically the backend parses the received data and dispatches to the correct callbacks if needed.

This function is typically called whenever your eventloop detects that data is available for read on the connection context's file descriptor.

Parameters

ctx	the connection context

Returns

-1 when failed reading, other values are considered as success and depends on the backend implementation, typically the number of bytes read are returned.

Definition at line 392 of file amxb_ba_connect.c.

                                               {
    int retval = -1;
    const amxb_be_funcs_t* fns = NULL;
 
    when_null(ctx, exit);
    when_null(ctx->bus_ctx, exit);
 
    fns = ctx->bus_fn;
    if(amxb_is_valid_be_func(fns, read, fns->read)) {
        retval = fns->read(ctx->bus_ctx);
    }
 
exit:
    return retval;
}

amxb_read_raw()

int amxb_read_raw	(	const amxb_bus_ctx_t *const	ctx,
		void *	buf,
		size_t	count
	)

Attempts to read up to count bytes from the file descriptor into the buffer starting at buf.

Reads data from the file descriptor of the connection context, and puts the read data in the provided bufffer, up to the given count bytes.

The data received is put in the buffer as is, not parsing is done.

This function is typically called whenever your eventloop detects that data is available for read on the connection context's file descriptor.

Note

do not use amxb_read and amxb_read_raw on the same context, only use one of them. When using this function it is up to the implementer to parse the received data and call any callbacks if needed.

Parameters

ctx	the connection context
buf	pointer to a memory block where data can be put
count	maximum number of bytes that can be put in the memory block

Returns

-1 when failed reading, other values are considered as success and depends on the backend implementation, typically the number of bytes read are returned.

Definition at line 408 of file amxb_ba_connect.c.

                                                                            {
    int retval = -1;
    const amxb_be_funcs_t* fns = NULL;
 
    when_null(ctx, exit);
    when_null(ctx->bus_ctx, exit);
    when_null(buf, exit);
    when_true(count == 0, exit);
 
    fns = ctx->bus_fn;
    if(amxb_is_valid_be_func(fns, read_raw, fns->read_raw)) {
        retval = fns->read_raw(ctx->bus_ctx, buf, count);
    }
 
exit:
    return retval;
}

amxb_set_access()

static void amxb_set_access ( amxb_bus_ctx_t *const  ctx, uint32_t  access  )

inlinestatic

Sets the access method.

Parameters

ctx	the connection context
access	the access method, must be one of AMXB_PUBLIC, AMXB_PROTECTED

Definition at line 355 of file amxb_connect.h.

                                                                 {
    if(ctx != NULL) {
        ctx->access = access;
    }
}