.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "ams::doc::pod3::ams 3" .TH ams::doc::pod3::ams 3 "2016-07-07" "perl v5.24.1" "AMS library functions" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" ams \- CCSDS Asynchronous Message Service(AMS) communications library .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #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] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The ams library provides functions enabling application software to use \s-1AMS\s0 to send and receive brief messages, up to 65000 bytes in length. It conforms to \s-1AMS\s0 Blue Book, including support for Remote \s-1AMS \s0(\s-1RAMS\s0). .PP In the \s-1ION\s0 implementation of \s-1RAMS,\s0 the \*(L"\s-1RAMS\s0 network protocol\*(R" may be either the \s-1DTN\s0 Bundle Protocol (\s-1RFC 5050\s0) or \*(-- mainly for testing purposes \*(-- the User Datagram Protocol (\s-1RFC 768\s0). \s-1BP\s0 is the default. When \s-1BP\s0 is used as the \s-1RAMS\s0 network protocol, endpoints are by default assumed to conform to the \*(L"ipn\*(R" endpoint identifier scheme with \fBnode number\fR set to the \s-1AMS \&\s0\fBcontinuum number\fR and \fBservice number\fR set to the \s-1AMS \s0\fBventure number\fR. .PP Note that \s-1RAMS\s0 functionality is enabled by instantiating a \fBramsgate\fR daemon, which is simply an \s-1AMS\s0 application program that acts as a gateway between the local \s-1AMS\s0 message space and the \s-1RAMS\s0 network. .PP \&\s-1AMS\s0 differs from other \s-1ION\s0 packages in that there is no utilization of non-volatile storage (aside from the \s-1BP\s0 functionality in \s-1RAMS,\s0 if applicable). Since there is no non-volatile \s-1AMS\s0 database, there is no \s-1AMS\s0 administration program and there are no library functions for attaching to or detaching from such a database. \s-1AMS\s0 is instantiated by commencing operation of the \&\s-1AMS\s0 real-time daemon \fBamsd\fR; once \fBamsd\fR is running, \s-1AMS\s0 application programs (\*(L"modules\*(R") can be started. All management of \s-1AMS\s0 operational state is performed automatically in real time. .PP However, \fBamsd\fR and the \s-1AMS\s0 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 \s-1XML\s0 statements conforming to the scheme described in the \fIamsxml\fR\|(5) man page, or a file of simple but less powerful configuration statements as described in the \fIamsrc\fR\|(5) man page. The \fBamsxml\fR alternative requires that the \fBexpat\fR \s-1XML\s0 parsing system be installed; the \fBamsrc\fR alternative was developed to simplify deployment of \s-1AMS\s0 in environments in which \fBexpat\fR 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. .PP The path name of the applicable configuration file may be passed as a command-line parameter to \fBamsd\fR and as a registration function parameter by any \s-1AMS\s0 application program. Note, though, that \fBramsgate\fR and the \&\s-1AMS\s0 test and utility programs included in \s-1ION\s0 always assume that the configuration file resides in the current working directory and that it is named \*(L"mib.amsrc\*(R" if \s-1AMS\s0 was built with \-DNOEXPAT, \*(L"amsmib.xml\*(R" otherwise. .PP The transport services that are made available to \s-1AMS\s0 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 \*(L"udp\*(R" transport service \*(-- nominally the most preferred because it imposes the least processing and transmission overhead \*(-- is included by setting the \-DUDPTS option. The \*(L"dgr\*(R" service is included by setting the \&\-DDGRTS option. The \*(L"vmq\*(R" (VxWorks message queue) service, supported only on VxWorks, is included by setting the \-DVMQTS option. The \*(L"tcp\*(R" transport service \*(-- selected only when its quality of service is required \*(-- is included by setting the \-DTCPTS option. .PP The operating state of any single \s-1AMS\s0 application program is managed in an opaque AmsModule object. This object is returned when the application begins \s-1AMS\s0 operations (that is, registers) and must be provided as an argument to most \s-1AMS\s0 functions. .IP "int ams_register(char *mibSource, char *tsorder, char *applicationName, char *authorityName, char *unitName, char *roleName, AmsModule *module)" 4 .IX Item "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 \fIunitName\fR) of a message space that is that portion of the venture identified by \&\fIapplicationName\fR and \fIauthorityName\fR that runs within the local \s-1AMS\s0 continuum. \fIroleName\fR identifies the role that this application will perform in this venture. The operating state of the registered application is returned in \fImodule\fR. .Sp 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 \fImibSource\fR. If \fImibSource\fR is the zero-length string ("") then the default configuration file name is used as noted above. If \&\fImibSource\fR is \s-1NULL\s0 then a rudimentary hard-coded default \s-1MIB,\s0 useful for basic testing purposes, is loaded. This default \s-1MIB\s0 defines a single venture for application \*(L"amsdemo\*(R" and authority \*(L"test\*(R", using only the \&\*(L"dgr\*(R" transport service, with the configuration server residing on the local host machine; subject \*(L"text\*(R" and roles \*(L"shell\*(R", \*(L"log\*(R", \*(L"pitch\*(R", and \*(L"catch\*(R" are defined. .Sp The \fItsorder\fR argument is normally \s-1NULL. \s0 If non-NULL it must be a NULL-terminated string of \s-1ASCII\s0 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 \fItsorder\fR string must represent the index position of one of the transport services within the array. For example, if services \*(L"udp\*(R", \*(L"dgr\*(R", \&\*(L"vmq\*(R", and \*(L"tcp\*(R" are all available in the array, a \fItsorder\fR string of \*(L"32\*(R" 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. .Sp Returns 0 on success. On any error, sets \fImodule\fR to \s-1NULL\s0 and returns \-1. .IP "int ams_unregister(AmsModule module)" 4 .IX Item "int ams_unregister(AmsModule module)" Reverses the operation of \fIams_unregister()\fR, destroying \fImodule\fR. Returns 0 on success, \-1 on any error. .IP "int ams_invite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)" 4 .IX Item "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 \fIsubjectNbr\fR. .Sp The invitation is extended only to modules registered in the role identified by \fIroleNbr\fR (where 0 indicates \*(L"all roles\*(R"), operating in the continuum identifed by \fIcontinuumNbr\fR (where 0 indicates \*(L"all continua\*(R"), and registered within the unit identified by \fIunitNbr\fR (where 0 indicates the venture's root unit) or any of that unit's subunits. These parameters define the \*(L"domain\*(R" of the invitation. .Sp Such messages should be sent at the priority indicated by \fIpriority\fR with flow label as indicated by \fIflowLabel\fR and with quality of service as indicated by \fIsequence\fR and \fIdiligence\fR. \fIpriority\fR 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 \s-1AMS\s0 itself; in the absence of defined flow labels, a value of 0 is typically used. These parameters define the \*(L"class of service\*(R" of the invitation. .Sp Returns 0 on success, \-1 on any error. .IP "int ams_disinvite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)" 4 .IX Item "int ams_disinvite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)" Rescinds the invitation characterized by the indicated subject and domain. Returns 0 on success, \-1 on any error. .IP "int ams_subscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)" 4 .IX Item "int ams_subscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)" Announces this module's subscription to messages on the indicated subject, constrained by the indicated domain, and transmitted subject to the indicated class of service. Note that subscriptions differ from invitations in that reception of these messages is actively solicited, not just permitted. .Sp Returns 0 on success, \-1 on any error. .IP "int ams_unsubscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)" 4 .IX Item "int ams_unsubscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)" Cancels the subscription characterized by the indicated subject and domain. Returns 0 on success, \-1 on any error. .IP "int ams_publish(AmsModule module, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)" 4 .IX Item "int ams_publish(AmsModule module, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)" Publishes \fIcontentLength\fR bytes of data starting at \fIcontent\fR as the content of a message that is sent to all modules whose subscriptions to \fIsubjectNbr\fR are characterized by a domain that includes this module. \fIpriority\fR and \&\fIflowLabel\fR, if non-zero, override class of service as requested in the subscriptions. \fIcontext\fR is an opaque \*(L"hint\*(R" to the receiving modules; its use is application-specific. .Sp Returns 0 on success, \-1 on any error. .IP "int ams_send(AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)" 4 .IX Item "int ams_send(AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)" Sends \fIcontentLength\fR bytes of data starting at \fIcontent\fR as the content of a message that is transmitted privately to the module in the continuum identified by \fIcontinuumNbr\fR (where 0 indicates \*(L"the local continuum\*(R") that is identified by \fIunitNbr\fR and \fImoduleNbr\fR \*(-- provided that \fImodule\fR is in the domain of one of that module's invitations on \fIsubjectNbr\fR. \&\fIpriority\fR and \fIflowLabel\fR, if non-zero, override class of service as requested in the invitation. \fIcontext\fR is an opaque \*(L"hint\*(R" to the receiving module; its use is application-specific. .Sp Returns 0 on success, \-1 on any error. .IP "int ams_query(AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context, int term, AmsEvent *event)" 4 .IX Item "int ams_query(AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context, int term, AmsEvent *event)" Sends a message exactly is described above for \fIams_send()\fR, but additionally suspends the delivery and processing of newly received messages until either (a) a \*(L"reply\*(R" message sent in response to this message is received or (b) the time interval indicated by \fIterm\fR, in seconds, expires. The event (reply or timeout) that ends the suspension of processing is provided in \fIevent\fR (as if from \fIams_get_event()\fR when the function returns. .Sp If \fIterm\fR is \s-1AMS_BLOCKING\s0 then the timeout interval is indefinite; only reception of a reply message enables the function to return. If \fIterm\fR is \&\s-1AMS_POLL\s0 then the function returns immediately, without waiting for a reply message. .Sp Returns 0 on success, \-1 on any error. .IP "int ams_reply(AmsModule module, AmsEvent msg, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content)" 4 .IX Item "int ams_reply(AmsModule module, AmsEvent msg, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content)" Sends a message exactly is described above for \fIams_send()\fR, except that the destination of the message is the sender of the message identified by \fImsg\fR and the \*(L"context\*(R" value included in the message is the context that was provided in \fImsg\fR. This message is identified as a \*(L"reply\*(R" message that will end the processing suspension resulting from transmission of \fImsg\fR if that message was issued by means of \fIams_query()\fR rather than \fIams_send()\fR. .Sp Returns 0 on success, \-1 on any error. .IP "int ams_announce(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)" 4 .IX Item "int ams_announce(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)" Sends a message exactly is described above for \fIams_send()\fR, except that one copy of the message is sent to every module in the domain of this function (role, continuum, unit) whose invitation for messages on this subject is itself characterized by a domain that includes the the sending module, rather than to any specific module. .Sp Returns 0 on success, \-1 on any error. .IP "int ams_get_event(AmsModule module, int term, AmsEvent *event)" 4 .IX Item "int ams_get_event(AmsModule module, int term, AmsEvent *event)" Returns in \fIevent\fR the next event in the queue of \s-1AMS\s0 events pending delivery to this module. If the event queue is empty at the time this function is called, processing is suspended until either an event is queued or the time interval indicated by \fIterm\fR, in seconds, expires. See \fIams_query()\fR above for the semantics of \fIterm\fR. When the function returns on expiration of \&\fIterm\fR, an event of type \s-1TIMEOUT_EVT\s0 is returned in \fIevent\fR. Otherwise the event will be of type \s-1AMS_MSG_EVT \s0(indicating arrival of a message), \&\s-1NOTICE_EVT \s0(indicating a change in the configuration of the message space), or \s-1USER_DEFINED_EVT \s0(indicating that application code posted an event). .Sp The nature of the event returned by \fIams_get_event()\fR can be determined by passing \fIevent\fR to \fIams_get_event_type()\fR as described below. Event type can then be used to determine whether the information content of the event must be obtained by calling \fIams_parse_msg()\fR, \fIams_parse_notice()\fR, or \&\fIams_parse_user_event()\fR. .Sp In any case, the memory occupied by \fIevent\fR must be released after the event object is no longer needed. The \fIams_recycle_event()\fR function is invoked for this purpose. .Sp Returns 0 on success, \-1 on any error. .IP "int ams_get_event_type(AmsEvent event)" 4 .IX Item "int ams_get_event_type(AmsEvent event)" Returns the event type of \fIevent\fR, or \-1 on any error. .IP "int ams_parse_msg(AmsEvent event, int *continuumNbr, int *unitNbr, int *moduleNbr, int *subjectNbr, int *contentLength, char **content, int *context, AmsMsgType *msgType, int *priority, unsigned char *flowLabel);" 4 .IX Item "int ams_parse_msg(AmsEvent event, int *continuumNbr, int *unitNbr, int *moduleNbr, int *subjectNbr, int *contentLength, char **content, int *context, AmsMsgType *msgType, int *priority, unsigned char *flowLabel);" Extracts all relevant information pertaining to the \s-1AMS\s0 message encapsulated in \fIevent\fR, populating the indicated fields. Must only be called when the event type of \fIevent\fR is known to be \s-1AMS_MSG_EVT.\s0 .Sp Returns 0 on success, \-1 on any error. .IP "int ams_parse_notice(AmsEvent event, AmsStateType *state, AmsChangeType *change, int *unitNbr, int *moduleNbr, int *roleNbr, int *domainContinuumNbr, int *domainUnitNbr, int *subjectNbr, int *priority, unsigned char *flowLabel, AmsSequence *sequence, AmsDiligence *diligence)" 4 .IX Item "int ams_parse_notice(AmsEvent event, AmsStateType *state, AmsChangeType *change, int *unitNbr, int *moduleNbr, int *roleNbr, int *domainContinuumNbr, int *domainUnitNbr, int *subjectNbr, int *priority, unsigned char *flowLabel, AmsSequence *sequence, AmsDiligence *diligence)" Extracts all relevant information pertaining to the \s-1AMS\s0 configuration change notice encapsulated in \fIevent\fR, populating the relevant fields. Must only be called when the event type of \fIevent\fR is known to be \s-1NOTICE_EVT.\s0 .Sp Note that different fields will be populated depending on the nature of the notice in \fIevent\fR. \fIstate\fR will be set to AmsRegistrationState, AmsInvitationState, or AmsSubscription state depending on whether the notice pertains to a change in module registration, a change in invitations, or a change in subscriptions. \fIchange\fR will be set to AmsStateBegins or AmsStateEnds depending on whether the notice pertains to the initiation or termination of a registration, invitation, or subscription. .Sp Returns 0 on success, \-1 on any error. .IP "int ams_post_user_event(AmsModule module, int userEventCode, int userEventDataLength, char *userEventData, int priority)" 4 .IX Item "int ams_post_user_event(AmsModule module, int userEventCode, int userEventDataLength, char *userEventData, int priority)" Posts a \*(L"user event\*(R" whose content is the \fIuserEventDataLength\fR bytes of data starting at \fIuserEventData\fR. \fIuserEventCode\fR is an application-specific value that is opaque to \s-1AMS. \s0\fIpriority\fR determines the event's position in the queue of events pending delivery to this module; it may be any integer in the range 0\-15, where 0 indicates the greatest urgency. (Note that user events can be delivered ahead of all message reception events if necessary.) .Sp Returns 0 on success, \-1 on any error. .IP "int ams_parse_user_event(AmsEvent event, int *code, int *dataLength, char **data)" 4 .IX Item "int ams_parse_user_event(AmsEvent event, int *code, int *dataLength, char **data)" Extracts all relevant information pertaining to the user event encapsulated in \fIevent\fR, populating the indicated fields. Must only be called when the event type of \fIevent\fR is known to be \s-1USER_DEFINED_EVT.\s0 .Sp Returns 0 on success, \-1 on any error. .IP "int ams_recycle_event(AmsEvent event)" 4 .IX Item "int ams_recycle_event(AmsEvent event)" Releases all memory occupied by \fIevent\fR. Returns 0 on success, \-1 on any error. .IP "int ams_set_event_mgr(AmsModule module, AmsEventMgt *rules)" 4 .IX Item "int ams_set_event_mgr(AmsModule module, AmsEventMgt *rules)" Starts a background thread that processes events queued for this module, handling each event in the manner indicated by \fIrules\fR. Returns 0 on success, \-1 on any error. .IP "void ams_remove_event_mgr(AmsModule module)" 4 .IX Item "void ams_remove_event_mgr(AmsModule module)" Terminates the background thread established to process events queued for this module. Returns 0 on success, \-1 on any error. .IP "int ams_get_module_nbr(AmsModule module)" 4 .IX Item "int ams_get_module_nbr(AmsModule module)" Returns the module number assigned to this module upon registration, or \-1 on any error. .IP "int ams_get_unit_nbr(AmsModule module)" 4 .IX Item "int ams_get_unit_nbr(AmsModule module)" Returns the unit number assigned to the unit within which this module registered, or \-1 on any error. .IP "Lyst ams_list_msgspaces(AmsModule module)" 4 .IX Item "Lyst ams_list_msgspaces(AmsModule module)" Returns a dynamically allocated linked list of all message spaces identified in the \s-1MIB\s0 for this module, or \-1 on any error. See \fIlyst\fR\|(3) for operations that can be performed on the returned linked list. .IP "int \fIams_get_continuum_nbr()\fR" 4 .IX Item "int ams_get_continuum_nbr()" Returns the continuum number assigned to the continuum within which this module operates, or \-1 on any error. .IP "int ams_rams_net_is_tree(AmsModule module)" 4 .IX Item "int ams_rams_net_is_tree(AmsModule module)" Returns 1 if the \s-1RAMS\s0 net for the venture in which this module is registered is configured as a tree, 0 if that \s-1RAMS\s0 net is configured as a mesh, \-1 on any error. .IP "int ams_continuum_is_neighbor(int continuumNbr)" 4 .IX Item "int ams_continuum_is_neighbor(int continuumNbr)" Returns 1 if \fIcontinuumNbr\fR identifies a continuum whose \s-1RAMS\s0 gateways are immediate neighbors (within the applicable \s-1RAMS\s0 networks) of the \&\s-1RAMS\s0 gateways in the local continuum. Returns 0 otherwise. .IP "char *ams_get_role_name(AmsModule module, int unitNbr, int moduleNbr)" 4 .IX Item "char *ams_get_role_name(AmsModule module, int unitNbr, int moduleNbr)" Returns the name of the role in which the module identified by \fIunitNbr\fR and \&\fImoduleNbr\fR registered, or \s-1NULL\s0 on any error. .IP "int ams_subunit_of(AmsModule module, int argUnitNbr, int refUnitNbr)" 4 .IX Item "int ams_subunit_of(AmsModule module, int argUnitNbr, int refUnitNbr)" Returns 1 if \fIargUnitNbr\fR identifies a unit that is wholly contained within the unit identified by \fIrefUnitNbr\fR, in the venture within which this module is registered. Returns 0 otherwise. .IP "int ams_lookup_unit_nbr(AmsModule module, char *unitName)" 4 .IX Item "int ams_lookup_unit_nbr(AmsModule module, char *unitName)" Returns the number assigned to the unit identified by \fIunitName\fR, in the venture within which this module is registered, or \-1 on any error. .IP "int ams_lookup_role_nbr(AmsModule module, char *roleName)" 4 .IX Item "int ams_lookup_role_nbr(AmsModule module, char *roleName)" Returns the number assigned to the role identified by \fIroleName\fR, in the venture within which this module is registered, or \-1 on any error. .IP "int ams_lookup_subject_nbr(AmsModule module, char *subjectName)" 4 .IX Item "int ams_lookup_subject_nbr(AmsModule module, char *subjectName)" Returns the number assigned to the subject identified by \fIsubjectName\fR, in the venture within which this module is registered, or \-1 on any error. .IP "int ams_lookup_continuum_nbr(AmsModule module, char *continuumName)" 4 .IX Item "int ams_lookup_continuum_nbr(AmsModule module, char *continuumName)" Returns the number of the continuum identified by \fIcontinuumName\fR, or \-1 on any error. .IP "char *ams_lookup_unit_name(AmsModule module, int unitNbr)" 4 .IX Item "char *ams_lookup_unit_name(AmsModule module, int unitNbr)" Returns the name of the unit identified by \fIunitNbr\fR, in the venture within which this module is registered, or \-1 on any error. .IP "char *ams_lookup_role_name(AmsModule module, int roleNbr)" 4 .IX Item "char *ams_lookup_role_name(AmsModule module, int roleNbr)" Returns the name of the role identified by \fIroleNbr\fR, in the venture within which this module is registered, or \-1 on any error. .IP "char *ams_lookup_subject_name(AmsModule module, int subjectNbr)" 4 .IX Item "char *ams_lookup_subject_name(AmsModule module, int subjectNbr)" Returns the name of the subject identified by \fIsubjectNbr\fR, in the venture within which this module is registered, or \-1 on any error. .IP "char *ams_lookup_continuum_name(AmsModule module, int continuumNbr)" 4 .IX Item "char *ams_lookup_continuum_name(AmsModule module, int continuumNbr)" Returns the name of the continuum identified by \fIcontinuumNbr\fR, or \-1 on any error. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIamsd\fR\|(1), \fIramsgate\fR\|(1), \fIamsxml\fR\|(5), \fIamsrc\fR\|(5)