libmctProgrammer’s Manual

mct(3)

Name

mct — MCT API

Synopsis

#include <mct/mct.h>
#include <mct/event.h>
#include <mct/session.h>

struct mct;

Link with -lmct.

Description

The MCT interface provides a programmatic way to control one or more instances of mctd. Communication is provided over a socket for an internal IPC protocol. This API exposes all features of the daemon which may be modified at runtime.

Functionality falls broadly into two categories, that pertaining to administration of active sessions, and that pertaining to retrieving events broadcast asynchronously to attached instances of libmct. These are provided by the <mct/session.h> and <mct/event.h> headers respectively.

The MCT daemon provides an arbitrary number of sessions. Each session represents an address for either incoming or outgoing datagrams. These may be created by mct_bridge and destroyed by mct_session_close.

The mct_session_*() functions operate on extant sessions.

The MCT daemon provides a mechanism for broadcasting events asynchronously to attached instances of libmct. Instances register their interest in receiving broadcasts by calling mct_event_attach. Incoming events pend reads in a set, and may be retrieved by calls to mct_event_read.

Each event represents a notification of a situation mctd encountered that did not directly result from a call to some action performed over IPC (that is, instantiated by one of the mct functions). Typically these notifications reflect error conditions, and are made available to applications for the sake of logging and user notification as per applications’ needs.

Events are categorised by type; these types are enumerated by the mct_event enum, defined by <mct/event.h>:

enum mct_event {
	MCT_SESSION_CLOSED,
	MCT_SESSION_OPENED,
	MCT_DROPPED_PACKET,
	MCT_SHORT_SEND
};

Each event is associated with an active session ID. These session IDs are unique per instance of mctd, but may have been created by a different mct handle. In other words, consider the broadcasts global notifications about the current activity of mctd rather than responses to any particular API calls.

Events have a serial ID and an associated error code. See mct_event_read for details on these.

Functions

<mct/mct.h>:

mct_init()

Create a mct handle.

mct_fini()

Destroy a mct handle.

<mct/session.h>:

mct_bridge()

Create a session.

mct_session_close()

Destroy a session.

mct_session_add()

Add a multicast group to a session.

mct_session_drop()

Drop a multicast group from a session.

mct_session_affinity()

Set multicast affinity for a session.

mct_session_ttl()

Set the multicast TTL for a session.

<mct/event.h>:

mct_event_attach()

Request event broadcasts.

mct_event_detach()

Revoke request for event broadcasts.

mct_event_read()

Retrieve a pending event.

mct_event_name()

Find a human-readable event name.

Notes

The design of the API attempts to integrate with standard POSIX constructs, in particular the sockaddr structure for specifying socket addresses. In doing so, standard name resolution interfaces such as getaddrinfo may be used, rather than duplicating their functionality in a less general manner.

See Also

mctd, mct_init, mct_bridge, mct_session_close, mct_session_add, mct_session_ttl, mct_event_attach, mct_event_name, mct_event_read, mct_conv, getaddrinfo.

History

libmct was designed and implemented by Katherine Flavel for Bubblephone Ltd.

Initial development of MCT was funded by 2iC Ltd.