Libxmtr Library

This is Info file libxmtr.info, produced by Makeinfo-1.64 from the input file libxmtr.texinfo.

Copyright (C) 1995 Loral Advanced Distributed Simulation, Inc.

File: libxmtr.info, Node: Top, Next: Overview, Prev: (./modsafprm), Up: (./modsafprm)

* Menu:

This is the top level menu of an info file. To go to a section in this menu, you should type "m" followed by the first few characters of the section you are interested. If you put the text cursor next to the section you are interested (use "C-n"), "m" will default to that section (you can then hit RETURN to go to the section).

* Overview::     Overview of libxmtr functionality
* Functions::      Descriptions of public functions

File: libxmtr.info, Node: Overview, Next: Functions, Prev: Top, Up: Top

Overview
********

LibXMTR is a vehicle subclass that handles sending, receiving, and caching DIS and SIMNET transmitter PDUS. LibXMTR provides a function to send out the XMTR PDU. And, when the XMTR PDU is sent out, the entry for the specific XMTR in the internal link-list will be updated.

A transmitter is uniquely identified by the entity_id/radio_id pair. For each vehicle, libxmtr maintains an internal link-list of transmitters that are active on that vehicle. LibXMTR holds the last information sent in a XMTR pdu. This is used when a radio library receives a signal PDU, it can query libxmtr for the last transmitter information associated with that signal PDU.

A callback event (*note CALLBACK_EVENT_PTR: (./libcallback)CALLBACK_EVENT_PTR.) is defined for each transmitter, and that event is fired when the transmitter ends a transmission (transitions from a "on, transmitting" state to an "on, not transmitting" or "off" state). Interested parties can subscribe to this event to be warned when a transmission ends.

When the xmtr PDU gets sent out, it will update the internal data for that transmitter. When the xmtr PDU is received describing a transmitter that it does not know about, it will create a new XMTR in the internal link-list for that (remote) vehicle.

LibXMTR provides external functions to retrieve the latest information about a specific XMTR. The only way to change the internal xmtr data is to send out a new xmtr PDU.

 File: libxmtr.info, Node: Functions, Prev: Overview, Up: Top

Functions
*********

The following sections describe each function provided by libxmtr including the format and meaning of its arguments, and the meaning of its return values (if any).

* Menu:

 File: libxmtr.info, Node: xmtr_create_xmtr, Next: xmtr_destroy_xmtr, Up: Functions

xmtr_create_xmtr
================
int16 xmtr_create_xmtr(entity_id, passed_radio_id, min_radio_id)
int32 entity_id;
int16 passed_radio_id;
int32 min_radio_id;

`entity_id'
Specifies the internal id of the entity to create xmtr on.

`passed_radio_id'
Specifies the radio_id to assign to this xmtr. If "-1" is passed, then the function will use the next unique radio_id.

`min_radio_id'
Specifies the minimum radio_id to assign to this xmtr. If a 0 is passed, no special action is taken. Otherwise, LibXMTR will try and find a radio_id that is above the minimum and is not used by any other Transmitter on the battlefield.

`xmtr_create_xmtr' creates an entry in the link-list of xmtrs for this vehicle. This is done for every unique radio_id/entity_id pair. So, this function will be called every time an instance of genradio is created. If "-1" is passed for the radio_id, xmtr_create_xmtr will go ahead and find the next unique radio_id and return it. If the radio_id is not "-1" then xmtr_create_xmtr will create the xmtr with the passed radio_id (this should only happen for remote xmtrs).  File: libxmtr.info, Node: xmtr_destroy_xmtr, Next: xmtr_entry_exist, Prev: xmtr_create_xmtr, Up: Functions

xmtr_destroy_xmtr
=================
void xmtr_destroy_xmtr(entity_id, radio_id)
int32 entity_id;
int32 radio_id;

`entity_id'
Specifies the internal id of the entity to destroy the xmtr
`radio_id'
Speicifies the radio_id that identifies the xmtr to destroy.
`xmtr_destroy_xmtr' uses the passed entity_id/radio_id pair to locate the correct xmtr and destroy (dealloc) the entry from the link-list.

 File: libxmtr.info, Node: xmtr_entry_exist, Next: xmtr_get_all, Prev: xmtr_destroy_xmtr, Up: Functions

xmtr_entry_exist
================
int32 xmtr_entry_exist(entity_id, radio_id)
int32 entity_id;
int16 radio_id;

`entity_id'
Specifies the internal id of the entity which the xmtr is part of.
`radio_id'
Speicifies the radio_id of the specific xmtr.
`xmtr_entry_exist' will use the entity_id/radio_id pair to search through the list of xmtrs for this vehicle and check to see if this xmtr already exists in the list.

 File: libxmtr.info, Node: xmtr_get_all, Next: xmtr_get_frequency, Prev: xmtr_entry_exist, Up: Functions

xmtr_get_all
============
void xmtr_get_all(entity_id, radio_id, xmtr_info)
int32 entity_id;
int16 radio_id;
XMTR_PDU_INFO *xmtr_info;

`entity_id'
Specifies the internal id of the entity which the xmtr is part of.
`radio_id'
Speicifies the radio_id of the specific xmtr.
`xmtr_info'
Specifies a location to pass back the xmtr information associated with this entity_id/radio_id pair.
`xmtr_get_all' will search through the xmtrs associated with the entity_id and will get all of the associated xmtr information for the correct xmtr and return this information in the passed xmtr_info memory block.

 File: libxmtr.info, Node: xmtr_get_frequency, Next: xmtr_init, Prev: xmtr_get_all, Up: Functions

xmtr_get_frequency
==================

int32 xmtr_get_frequency(entity_id, radio_id)
int32 entity_id;
int16 radio_id;
`entity_id'
Specifies the internal id of the entity which the xmtr is part of.
`radio_id'
Speicifies the radio_id of the specific xmtr.
`xmtr_get_frequency' will search through the xmtrs associated with the entity_id and will get the frequency from the internal data for the xmtr. The data is accessed from the entity_id and radio_id.

 File: libxmtr.info, Node: xmtr_init, Next: xmtr_send_pdu, Prev: xmtr_get_frequency, Up: Functions

xmtr_init
=========
#include <libctdb.h>
void xmtr_init(tick_rate, ctdb)
uint32       tick_rate;
CTDB       *ctdb;
`tick_rate'
Specifies the tick_rate of entities (VTAB_REMOTE_RADIO) created if libXMTR gets a TRANSMITTER PDU from an unknown entity.
`ctdb'
Specifies the compact terrain database to use for libxmtr-created entities.
`xmtr_init' initializes libxmtr. Call this before any other libxmtr function.

 File: libxmtr.info, Node: xmtr_send_pdu, Next: xmtr_get_end_xmit_event, Prev: xmtr_init, Up: Functions

xmtr_send_pdu
=============
void xmtr_send_pdu(entity_id, radio_id, xmtr_info)
int32      entity_id;
int32      radio_id;
XMTR_PDU_INFO *xmtr_info;
`entity_id'
Specifies the internal id of the entity sending out the PDU
`radio_id'
Speicifies the radio_id of the specific xmtr.
xmtr_info'
Specifies all of the xmtr data that needs to be filled into the PDU.
`xmtr_send_pdu' fills out a XMTR PDU with the passed information and sends out the PDU. When the PDU is sent out, the internal xmtr is updated with the passed info.

 File: libxmtr.info, Node: xmtr_get_end_xmit_event, Next: xmtr_print_xmtr_info, Prev: xmtr_send_pdu, Up: Functions

xmtr_get_end_xmit_event
=======================

CALLBACK_EVENT_PTR xmtr_get_end_xmit_event(entity_id, radio_id)
int32      entity_id;
int32      radio_id;
`entity_id'
Specifies the internal id of the entity sending out the PDU
`radio_id'
Specifies the radio_id of the specific xmtr.
`xmtr_get_end_xmit_event' returns a `libcallback' event which is fired whenever the transmitter ends a transmission. Interested parties may subscribe to this event via `callback_register_handler' (*note callback_register_handler: (./libcallback)callback_register_handler.). The handler should have the following form:
void handle_end_xmit(entity_id, radio_id, user_data)
int32 entity_id;
int32 radio_id;
ADDRESS user_data;

The passed `entity_id' and `radio_id' identify the (no longer) transmitting entity.

 File: libxmtr.info, Node: xmtr_print_xmtr_info, Next: xmtr_get_rti_id, Prev: xmtr_get_end_xmit_event, Up: Functions

xmtr_print_xmtr_info
====================
void xmtr_print_xmtr_info(info)
XMTR_PDU_INFO *info;

`info'
Specifies all of the xmtr data that needs to be filled into the PDU.
`xmtr_print_xmtr_info' prints the contents of the structure `info'.

 File: libxmtr.info, Node: xmtr_get_rti_id, Prev: xmtr_print_xmtr_info, Up: Functions

xmtr_get_rti_id
===============

int32 xmtr_get_rti_id(entity_id, radio_id)
int32 entity_id;
int32 radio_id;

`entity_id, radio_id'
Specifies the radio
`xmtr_get_rti_id' gets the vehicle ID associated with a transmitter. When using the RTI, all radios are placed in the vehicle table.

 Tag Table:

 End Tag Table