3
ams - CCSDS Asynchronous Message Service(AMS) communications library
9
typedef void (*AmsMsgHandler)(AmsModule module,
21
unsigned char flowLabel);
23
typedef void (*AmsRegistrationHandler)(AmsModule module,
30
typedef void (*AmsUnregistrationHandler)(AmsModule module,
36
typedef void (*AmsInvitationHandler)(AmsModule module,
42
int domainContinuumNbr,
46
unsigned char flowLabel,
48
AmsDiligence diligence);
50
typedef void (*AmsDisinvitationHandler)(AmsModule module,
56
int domainContinuumNbr,
60
typedef void (*AmsSubscriptionHandler)(AmsModule module,
66
int domainContinuumNbr,
70
unsigned char flowLabel,
72
AmsDiligence diligence);
74
typedef void (*AmsUnsubscriptionHandler)(AmsModule module,
80
int domainContinuumNbr,
84
typedef void (*AmsUserEventHandler)(AmsModule module,
91
typedef void (*AmsMgtErrHandler)(void *userData,
96
AmsMsgHandler msgHandler;
97
void *msgHandlerUserData;
98
AmsRegistrationHandler registrationHandler;
99
void *registrationHandlerUserData;
100
AmsUnregistrationHandler unregistrationHandler;
101
void *unregistrationHandlerUserData;
102
AmsInvitationHandler invitationHandler;
103
void *invitationHandlerUserData;
104
AmsDisinvitationHandler disinvitationHandler;
105
void *disinvitationHandlerUserData;
106
AmsSubscriptionHandler subscriptionHandler;
107
void *subscriptionHandlerUserData;
108
AmsUnsubscriptionHandler unsubscriptionHandler;
109
void *unsubscriptionHandlerUserData;
110
AmsUserEventHandler userEventHandler;
111
void *userEventHandlerUserData;
112
AmsMgtErrHandler errHandler;
113
void *errHandlerUserData;
130
AmsRegistrationState,
149
[see description for available functions]
153
The ams library provides functions enabling application software to use AMS
154
to send and receive brief messages, up to 65000 bytes in length. It conforms
155
to AMS Blue Book, including support for Remote AMS (RAMS).
157
In the ION implementation of RAMS, the "RAMS network protocol" may be either
158
the DTN Bundle Protocol (RFC 5050) or -- mainly for testing purposes -- the
159
User Datagram Protocol (RFC 768). BP is the default. When BP is used as
160
the RAMS network protocol, endpoints are by default assumed to conform to
161
the "ipn" endpoint identifier scheme with B<node number> set to the AMS
162
B<continuum number> and B<service number> set to the AMS B<venture number>.
164
Note that RAMS functionality is enabled by instantiating a B<ramsgate> daemon,
165
which is simply an AMS application program that acts as a gateway between the
166
local AMS message space and the RAMS network.
168
AMS differs from other ION packages in that there is no utilization of
169
non-volatile storage (aside from the BP functionality in RAMS, if applicable).
170
Since there is no non-volatile AMS database, there is no AMS administration
171
program and there are no library functions for attaching to or detaching
172
from such a database. AMS is instantiated by commencing operation of the
173
AMS real-time daemon B<amsd>; once B<amsd> is running, AMS application
174
programs ("modules") can be started. All management of AMS operational
175
state is performed automatically in real time.
177
However, B<amsd> and the AMS application programs all require
178
access to a common store of configuration data at startup in order to load
179
their Management Information Bases. This configuration data must reside in
180
a readable file, which may take either of two forms: a file of XML statements
181
conforming to the scheme described in the amsxml(5) man page, or a file of
182
simple but less powerful configuration statements as described in the amsrc(5)
183
man page. The B<amsxml> alternative requires that the B<expat> XML parsing
184
system be installed; the B<amsrc> alternative was developed to simplify
185
deployment of AMS in environments in which B<expat> is not readily supported.
186
Selection of the configuration file format is a compile-time decision,
187
implemented by setting (or not setting) the -DNOEXPAT compiler option.
189
The path name of the applicable configuration file may be passed as a
190
command-line parameter to B<amsd> and as a registration function parameter
191
by any AMS application program. Note, though, that B<ramsgate> and the
192
AMS test and utility programs included in ION always assume that the
193
configuration file resides in the current working directory and that it is
194
named "mib.amsrc" if AMS was built with -DNOEXPAT, "amsmib.xml" otherwise.
196
The transport services that are made available to AMS communicating entities
197
are declared by the transportServiceLoaders array in the libams.c source
198
file. This array is fixed at compile time. The order of preference of the
199
transport services in the array is hard-coded, but the inclusion or omission
200
of individual transport services is controlled by setting compiler options.
201
The "udp" transport service -- nominally the most preferred because it
202
imposes the least processing and transmission overhead -- is included by
203
setting the -DUDPTS option. The "dgr" service is included by setting the
204
-DDGRTS option. The "vmq" (VxWorks message queue) service, supported only
205
on VxWorks, is included by setting the -DVMQTS option. The "tcp" transport
206
service -- selected only when its quality of service is required -- is
207
included by setting the -DTCPTS option.
209
The operating state of any single AMS application program is managed in
210
an opaque AmsModule object. This object is returned when the application
211
begins AMS operations (that is, registers) and must be provided as an
212
argument to most AMS functions.
216
=item int ams_register(char *mibSource, char *tsorder, char *applicationName, char *authorityName, char *unitName, char *roleName, AmsModule *module)
218
Registers the application within a cell (identified by I<unitName>) of a
219
message space that is that portion of the venture identified by
220
I<applicationName> and I<authorityName> that runs within the local AMS
221
continuum. I<roleName> identifies the role that this application will
222
perform in this venture. The operating state of the registered application
223
is returned in I<module>.
225
The application module's identifying parameters are validated against the
226
configuration information in the applicable Management Information Base,
227
which is automatically loaded from the file whose pathname is provided
228
in I<mibSource>. If I<mibSource> is the zero-length string ("") then
229
the default configuration file name is used as noted above. If
230
I<mibSource> is NULL then a rudimentary hard-coded default MIB, useful
231
for basic testing purposes, is loaded. This default MIB defines a single
232
venture for application "amsdemo" and authority "test", using only the
233
"dgr" transport service, with the configuration server residing on the
234
local host machine; subject "text" and roles "shell", "log", "pitch",
235
and "catch" are defined.
237
The I<tsorder> argument is normally NULL. If non-NULL it must be a
238
NULL-terminated string of ASCII numeric digits '0' through '9' identifying
239
an alternative transport service preference order that overrides the standard
240
transport service preference order defined by the hard-coded array of
241
transportServiceLoaders in the libams.c source file. Each character of
242
the I<tsorder> string must represent the index position of one of the
243
transport services within the array. For example, if services "udp", "dgr",
244
"vmq", and "tcp" are all available in the array, a I<tsorder> string of "32"
245
would indicate that this application will only communicate using the tcp
246
and vmq services; services 0 (udp) and 1 (dgr) will not be used, and tcp
247
is preferred to vmq when both are candidate services for transmission of
250
Returns 0 on success. On any error, sets I<module> to NULL and returns -1.
252
=item int ams_unregister(AmsModule module)
254
Reverses the operation of ams_unregister(), destroying I<module>. Returns
255
0 on success, -1 on any error.
257
=item int ams_invite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)
259
Announces this module's agreement to receive messages on the subject
260
identified by I<subjectNbr>.
262
The invitation is extended only to modules registered in the role identified
263
by I<roleNbr> (where 0 indicates "all roles"), operating in the continuum
264
identifed by I<continuumNbr> (where 0 indicates "all continua"), and
265
registered within the unit identified by I<unitNbr> (where 0 indicates
266
the venture's root unit) or any of that unit's subunits. These parameters
267
define the "domain" of the invitation.
269
Such messages should be sent at the priority indicated by I<priority> with
270
flow label as indicated by I<flowLabel> and with quality of service as
271
indicated by I<sequence> and I<diligence>. I<priority> must be an integer
272
in the range 1-15, where priority 1 indicates the greatest urgency. Flow
273
labels are passed through to transport services and are opaque to AMS itself;
274
in the absence of defined flow labels, a value of 0 is typically used. These
275
parameters define the "class of service" of the invitation.
277
Returns 0 on success, -1 on any error.
279
=item int ams_disinvite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)
281
Rescinds the invitation characterized by the indicated subject and
282
domain. Returns 0 on success, -1 on any error.
284
=item int ams_subscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)
286
Announces this module's subscription to messages on the indicated subject,
287
constrained by the indicated domain, and transmitted subject to the indicated
288
class of service. Note that subscriptions differ from invitations in that
289
reception of these messages is actively solicited, not just permitted.
291
Returns 0 on success, -1 on any error.
293
=item int ams_unsubscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)
295
Cancels the subscription characterized by the indicated subject and
296
domain. Returns 0 on success, -1 on any error.
298
=item int ams_publish(AmsModule module, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)
300
Publishes I<contentLength> bytes of data starting at I<content> as the content
301
of a message that is sent to all modules whose subscriptions to I<subjectNbr>
302
are characterized by a domain that includes this module. I<priority> and
303
I<flowLabel>, if non-zero, override class of service as requested in the
304
subscriptions. I<context> is an opaque "hint" to the receiving modules;
305
its use is application-specific.
307
Returns 0 on success, -1 on any error.
309
=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)
311
Sends I<contentLength> bytes of data starting at I<content> as the content
312
of a message that is transmitted privately to the module in the continuum
313
identified by I<continuumNbr> (where 0 indicates "the local continuum") that
314
is identified by I<unitNbr> and I<moduleNbr> -- provided that I<module> is
315
in the domain of one of that module's invitations on I<subjectNbr>.
316
I<priority> and I<flowLabel>, if non-zero, override class of service as
317
requested in the invitation. I<context> is an opaque "hint" to the receiving
318
module; its use is application-specific.
320
Returns 0 on success, -1 on any error.
322
=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)
324
Sends a message exactly is described above for ams_send(), but additionally
325
suspends the delivery and processing of newly received messages until either
326
(a) a "reply" message sent in response to this message is received or (b) the
327
time interval indicated by I<term>, in seconds, expires. The event (reply or
328
timeout) that ends the suspension of processing is provided in I<event> (as
329
if from ams_get_event() when the function returns.
331
If I<term> is AMS_BLOCKING then the timeout interval is indefinite; only
332
reception of a reply message enables the function to return. If I<term> is
333
AMS_POLL then the function returns immediately, without waiting for a reply
336
Returns 0 on success, -1 on any error.
338
=item int ams_reply(AmsModule module, AmsEvent msg, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content)
340
Sends a message exactly is described above for ams_send(), except that the
341
destination of the message is the sender of the message identified by I<msg>
342
and the "context" value included in the message is the context that was
343
provided in I<msg>. This message is identified as a "reply" message that
344
will end the processing suspension resulting from transmission of I<msg> if
345
that message was issued by means of ams_query() rather than ams_send().
347
Returns 0 on success, -1 on any error.
349
=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)
351
Sends a message exactly is described above for ams_send(), except that one
352
copy of the message is sent to every module in the domain of this function
353
(role, continuum, unit) whose invitation for messages on this subject is
354
itself characterized by a domain that includes the the sending module, rather
355
than to any specific module.
357
Returns 0 on success, -1 on any error.
359
=item int ams_get_event(AmsModule module, int term, AmsEvent *event)
361
Returns in I<event> the next event in the queue of AMS events pending delivery
362
to this module. If the event queue is empty at the time this function is
363
called, processing is suspended until either an event is queued or the time
364
interval indicated by I<term>, in seconds, expires. See ams_query() above
365
for the semantics of I<term>. When the function returns on expiration of
366
I<term>, an event of type TIMEOUT_EVT is returned in I<event>. Otherwise
367
the event will be of type AMS_MSG_EVT (indicating arrival of a message),
368
NOTICE_EVT (indicating a change in the configuration of the message space),
369
or USER_DEFINED_EVT (indicating that application code posted an event).
371
The nature of the event returned by ams_get_event() can be determined by
372
passing I<event> to ams_get_event_type() as described below. Event type can
373
then be used to determine whether the information content of the event
374
must be obtained by calling ams_parse_msg(), ams_parse_notice(), or
375
ams_parse_user_event().
377
In any case, the memory occupied by I<event> must be released after the
378
event object is no longer needed. The ams_recycle_event() function is
379
invoked for this purpose.
381
Returns 0 on success, -1 on any error.
383
=item int ams_get_event_type(AmsEvent event)
385
Returns the event type of I<event>, or -1 on any error.
387
=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);
389
Extracts all relevant information pertaining to the AMS message encapsulated
390
in I<event>, populating the indicated fields. Must only be called when
391
the event type of I<event> is known to be AMS_MSG_EVT.
393
Returns 0 on success, -1 on any error.
395
=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)
397
Extracts all relevant information pertaining to the AMS configuration change
398
notice encapsulated in I<event>, populating the relevant fields. Must only
399
be called when the event type of I<event> is known to be NOTICE_EVT.
401
Note that different fields will be populated depending on the nature of the
402
notice in I<event>. I<state> will be set to AmsRegistrationState,
403
AmsInvitationState, or AmsSubscription state depending on whether the
404
notice pertains to a change in module registration, a change in invitations,
405
or a change in subscriptions. I<change> will be set to AmsStateBegins or
406
AmsStateEnds depending on whether the notice pertains to the initiation or
407
termination of a registration, invitation, or subscription.
409
Returns 0 on success, -1 on any error.
411
=item int ams_post_user_event(AmsModule module, int userEventCode, int userEventDataLength, char *userEventData, int priority)
413
Posts a "user event" whose content is the I<userEventDataLength> bytes of
414
data starting at I<userEventData>. I<userEventCode> is an application-specific
415
value that is opaque to AMS. I<priority> determines the event's position in
416
the queue of events pending delivery to this module; it may be any integer
417
in the range 0-15, where 0 indicates the greatest urgency. (Note that user
418
events can be delivered ahead of all message reception events if necessary.)
420
Returns 0 on success, -1 on any error.
422
=item int ams_parse_user_event(AmsEvent event, int *code, int *dataLength, char **data)
424
Extracts all relevant information pertaining to the user event encapsulated
425
in I<event>, populating the indicated fields. Must only be called when
426
the event type of I<event> is known to be USER_DEFINED_EVT.
428
Returns 0 on success, -1 on any error.
430
=item int ams_recycle_event(AmsEvent event)
432
Releases all memory occupied by I<event>. Returns 0 on success, -1 on any
435
=item int ams_set_event_mgr(AmsModule module, AmsEventMgt *rules)
437
Starts a background thread that processes events queued for this module,
438
handling each event in the manner indicated by I<rules>. Returns 0 on
439
success, -1 on any error.
441
=item void ams_remove_event_mgr(AmsModule module)
443
Terminates the background thread established to process events queued for
444
this module. Returns 0 on success, -1 on any error.
446
=item int ams_get_module_nbr(AmsModule module)
448
Returns the module number assigned to this module upon registration, or -1
451
=item int ams_get_unit_nbr(AmsModule module)
453
Returns the unit number assigned to the unit within which this module
454
registered, or -1 on any error.
456
=item Lyst ams_list_msgspaces(AmsModule module)
458
Returns a dynamically allocated linked list of all message spaces identified
459
in the MIB for this module, or -1 on any error. See lyst(3) for operations
460
that can be performed on the returned linked list.
462
=item int ams_get_continuum_nbr()
464
Returns the continuum number assigned to the continuum within which this
465
module operates, or -1 on any error.
467
=item int ams_rams_net_is_tree(AmsModule module)
469
Returns 1 if the RAMS net for the venture in which this module is registered
470
is configured as a tree, 0 if that RAMS net is configured as a mesh, -1 on
473
=item int ams_continuum_is_neighbor(int continuumNbr)
475
Returns 1 if I<continuumNbr> identifies a continuum whose RAMS gateways
476
are immediate neighbors (within the applicable RAMS networks) of the
477
RAMS gateways in the local continuum. Returns 0 otherwise.
479
=item char *ams_get_role_name(AmsModule module, int unitNbr, int moduleNbr)
481
Returns the name of the role in which the module identified by I<unitNbr> and
482
I<moduleNbr> registered, or NULL on any error.
484
=item int ams_subunit_of(AmsModule module, int argUnitNbr, int refUnitNbr)
486
Returns 1 if I<argUnitNbr> identifies a unit that is wholly contained within
487
the unit identified by I<refUnitNbr>, in the venture within which this
488
module is registered. Returns 0 otherwise.
490
=item int ams_lookup_unit_nbr(AmsModule module, char *unitName)
492
Returns the number assigned to the unit identified by I<unitName>, in
493
the venture within which this module is registered, or -1 on any error.
495
=item int ams_lookup_role_nbr(AmsModule module, char *roleName)
497
Returns the number assigned to the role identified by I<roleName>, in
498
the venture within which this module is registered, or -1 on any error.
500
=item int ams_lookup_subject_nbr(AmsModule module, char *subjectName)
502
Returns the number assigned to the subject identified by I<subjectName>, in
503
the venture within which this module is registered, or -1 on any error.
505
=item int ams_lookup_continuum_nbr(AmsModule module, char *continuumName)
507
Returns the number of the continuum identified by I<continuumName>, or -1
510
=item char *ams_lookup_unit_name(AmsModule module, int unitNbr)
512
Returns the name of the unit identified by I<unitNbr>, in
513
the venture within which this module is registered, or -1 on any error.
515
=item char *ams_lookup_role_name(AmsModule module, int roleNbr)
517
Returns the name of the role identified by I<roleNbr>, in
518
the venture within which this module is registered, or -1 on any error.
520
=item char *ams_lookup_subject_name(AmsModule module, int subjectNbr)
522
Returns the name of the subject identified by I<subjectNbr>, in
523
the venture within which this module is registered, or -1 on any error.
525
=item char *ams_lookup_continuum_name(AmsModule module, int continuumNbr)
527
Returns the name of the continuum identified by I<continuumNbr>, or -1
534
amsd(1), ramsgate(1), amsxml(5), amsrc(5)
added
removed
ams/doc/pod3/ams.pod
