Ubuntu Manpage: ams - CCSDS Asynchronous Message Service(AMS) communications library

NAME

       ams - CCSDS Asynchronous Message Service(AMS) communications library

SYNOPSIS

           #include "ams.h"

           typedef void                (*AmsMsgHandler)(AmsModule module,
                                               void *userData,
                                               AmsEvent *eventRef,
                                               int continuumNbr,
                                               int unitNbr,
                                               int moduleNbr,
                                               int subjectNbr,
                                               int contentLength,
                                               char *content,
                                               int context,
                                               AmsMsgType msgType,
                                               int priority,
                                               unsigned char flowLabel);

           typedef void                (*AmsRegistrationHandler)(AmsModule module,
                                               void *userData,
                                               AmsEvent *eventRef,
                                               int unitNbr,
                                               int moduleNbr,
                                               int roleNbr);

           typedef void                (*AmsUnregistrationHandler)(AmsModule module,
                                               void *userData,
                                               AmsEvent *eventRef,
                                               int unitNbr,
                                               int moduleNbr);

           typedef void                (*AmsInvitationHandler)(AmsModule module,
                                               void *userData,
                                               AmsEvent *eventRef,
                                               int unitNbr,
                                               int moduleNbr,
                                               int domainRoleNbr,
                                               int domainContinuumNbr,
                                               int domainUnitNbr,
                                               int subjectNbr,
                                               int priority,
                                               unsigned char flowLabel,
                                               AmsSequence sequence,
                                               AmsDiligence diligence);

           typedef void                (*AmsDisinvitationHandler)(AmsModule module,
                                               void *userData,
                                               AmsEvent *eventRef,
                                               int unitNbr,
                                               int moduleNbr,
                                               int domainRoleNbr,
                                               int domainContinuumNbr,
                                               int domainUnitNbr,
                                               int subjectNbr);

           typedef void                (*AmsSubscriptionHandler)(AmsModule module,
                                               void *userData,
                                               AmsEvent *eventRef,
                                               int unitNbr,
                                               int moduleNbr,
                                               int domainRoleNbr,
                                               int domainContinuumNbr,
                                               int domainUnitNbr,
                                               int subjectNbr,
                                               int priority,
                                               unsigned char flowLabel,
                                               AmsSequence sequence,
                                               AmsDiligence diligence);

           typedef void                (*AmsUnsubscriptionHandler)(AmsModule module,
                                               void *userData,
                                               AmsEvent *eventRef,
                                               int unitNbr,
                                               int moduleNbr,
                                               int domainRoleNbr,
                                               int domainContinuumNbr,
                                               int domainUnitNbr,
                                               int subjectNbr);

           typedef void                (*AmsUserEventHandler)(AmsModule module,
                                               void *userData,
                                               AmsEvent *eventRef,
                                               int code,
                                               int dataLength,
                                               char *data);

           typedef void                (*AmsMgtErrHandler)(void *userData,
                                               AmsEvent *eventRef);

           typedef struct
           {
               AmsMsgHandler                   msgHandler;
               void                            *msgHandlerUserData;
               AmsRegistrationHandler          registrationHandler;
               void                            *registrationHandlerUserData;
               AmsUnregistrationHandler        unregistrationHandler;
               void                            *unregistrationHandlerUserData;
               AmsInvitationHandler            invitationHandler;
               void                            *invitationHandlerUserData;
               AmsDisinvitationHandler         disinvitationHandler;
               void                            *disinvitationHandlerUserData;
               AmsSubscriptionHandler          subscriptionHandler;
               void                            *subscriptionHandlerUserData;
               AmsUnsubscriptionHandler        unsubscriptionHandler;
               void                            *unsubscriptionHandlerUserData;
               AmsUserEventHandler             userEventHandler;
               void                            *userEventHandlerUserData;
               AmsMgtErrHandler                errHandler;
               void                            *errHandlerUserData;
           } AmsEventMgt;

           typedef enum
           {
               AmsArrivalOrder = 0,
               AmsTransmissionOrder
           } AmsSequence;

           typedef enum
           {
               AmsBestEffort = 0,
               AmsAssured
           } AmsDiligence;

           typedef enum
           {
               AmsRegistrationState,
               AmsInvitationState,
               AmsSubscriptionState
           } AmsStateType;

           typedef enum
           {
               AmsStateBegins = 1,
               AmsStateEnds
           } AmsChangeType;

           typedef enum
           {
               AmsMsgUnary = 0,
               AmsMsgQuery,
               AmsMsgReply,
               AmsMsgNone
           } AmsMsgType;

           [see description for available functions]

DESCRIPTION

The ams library provides functions enabling application software to use AMS to send and receive brief
messages, up to 65000 bytes in length. It conforms to AMS Blue Book, including support for Remote AMS
(RAMS).

In the ION implementation of RAMS, the "RAMS network protocol" may be either the DTN Bundle Protocol (RFC
5050) or -- mainly for testing purposes -- the User Datagram Protocol (RFC 768). BP is the default.
When BP is used as the RAMS network protocol, endpoints are by default assumed to conform to the "ipn"
endpoint identifier scheme with node number set to the AMS continuum number and service number set to the
AMS venture number.

Note that RAMS functionality is enabled by instantiating a ramsgate daemon, which is simply an AMS
application program that acts as a gateway between the local AMS message space and the RAMS network.

AMS differs from other ION packages in that there is no utilization of non-volatile storage (aside from
the BP functionality in RAMS, if applicable). Since there is no non-volatile AMS database, there is no
AMS administration program and there are no library functions for attaching to or detaching from such a
database. AMS is instantiated by commencing operation of the AMS real-time daemon amsd; once amsd is
running, AMS application programs ("modules") can be started. All management of AMS operational state is
performed automatically in real time.

However, amsd and the AMS application programs all require access to a common store of configuration data
at startup in order to load their Management Information Bases. This configuration data must reside in a
readable file, which may take either of two forms: a file of XML statements conforming to the scheme
described in the amsxml(5) man page, or a file of simple but less powerful configuration statements as
described in the amsrc(5) man page. The amsxml alternative requires that the expat XML parsing system be
installed; the amsrc alternative was developed to simplify deployment of AMS in environments in which
expat is not readily supported. Selection of the configuration file format is a compile-time decision,
implemented by setting (or not setting) the -DNOEXPAT compiler option.

The path name of the applicable configuration file may be passed as a command-line parameter to amsd and
as a registration function parameter by any AMS application program. Note, though, that ramsgate and the
AMS test and utility programs included in ION always assume that the configuration file resides in the
current working directory and that it is named "mib.amsrc" if AMS was built with -DNOEXPAT, "amsmib.xml"
otherwise.

The transport services that are made available to AMS communicating entities are declared by the
transportServiceLoaders array in the libams.c source file. This array is fixed at compile time. The
order of preference of the transport services in the array is hard-coded, but the inclusion or omission
of individual transport services is controlled by setting compiler options. The "udp" transport service
-- nominally the most preferred because it imposes the least processing and transmission overhead -- is
included by setting the -DUDPTS option. The "dgr" service is included by setting the -DDGRTS option.
The "vmq" (VxWorks message queue) service, supported only on VxWorks, is included by setting the -DVMQTS
option. The "tcp" transport service -- selected only when its quality of service is required -- is
included by setting the -DTCPTS option.

The operating state of any single AMS application program is managed in an opaque AmsModule object. This
object is returned when the application begins AMS operations (that is, registers) and must be provided
as an argument to most AMS functions.

int ams_register(char *mibSource, char *tsorder, char *applicationName, char *authorityName, char
*unitName, char *roleName, AmsModule *module)
Registers the application within a cell (identified by unitName) of a message space that is that
portion of the venture identified by applicationName and authorityName that runs within the local AMS
continuum. roleName identifies the role that this application will perform in this venture. The
operating state of the registered application is returned in module.

The application module's identifying parameters are validated against the configuration information
in the applicable Management Information Base, which is automatically loaded from the file whose
pathname is provided in mibSource. If mibSource is the zero-length string ("") then the default
configuration file name is used as noted above. If mibSource is NULL then a rudimentary hard-coded
default MIB, useful for basic testing purposes, is loaded. This default MIB defines a single venture
for application "amsdemo" and authority "test", using only the "dgr" transport service, with the
configuration server residing on the local host machine; subject "text" and roles "shell", "log",
"pitch", and "catch" are defined.

The tsorder argument is normally NULL. If non-NULL it must be a NULL-terminated string of ASCII
numeric digits '0' through '9' identifying an alternative transport service preference order that
overrides the standard transport service preference order defined by the hard-coded array of
transportServiceLoaders in the libams.c source file. Each character of the tsorder string must
represent the index position of one of the transport services within the array. For example, if
services "udp", "dgr", "vmq", and "tcp" are all available in the array, a tsorder string of "32"
would indicate that this application will only communicate using the tcp and vmq services; services 0
(udp) and 1 (dgr) will not be used, and tcp is preferred to vmq when both are candidate services for
transmission of a given message.

Returns 0 on success. On any error, sets module to NULL and returns -1.

int ams_unregister(AmsModule module)
Reverses the operation of ams_unregister(), destroying module. Returns 0 on success, -1 on any
error.

int ams_invite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int
priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)
Announces this module's agreement to receive messages on the subject identified by subjectNbr.

The invitation is extended only to modules registered in the role identified by roleNbr (where 0
indicates "all roles"), operating in the continuum identifed by continuumNbr (where 0 indicates "all
continua"), and registered within the unit identified by unitNbr (where 0 indicates the venture's
root unit) or any of that unit's subunits. These parameters define the "domain" of the invitation.

Such messages should be sent at the priority indicated by priority with flow label as indicated by
flowLabel and with quality of service as indicated by sequence and diligence. priority must be an
integer in the range 1-15, where priority 1 indicates the greatest urgency. Flow labels are passed
through to transport services and are opaque to AMS itself; in the absence of defined flow labels, a
value of 0 is typically used. These parameters define the "class of service" of the invitation.