LGMP Programming Interface

(Version 2.0)

---

lgmp_init
lgmp_send           (new parameters since version 2.0)
lgmp_sendstatus  (new)
lgmp_receive
lgmp_end
lgmp_abort

Below is the description of these library calls
 

NAME

lgmp_init - LGMP context initialization and configuration

SYNOPSIS

#include "lgmp.h"

int  lgmp_init( lgmp_init_t   *init,
                const char    *mcastgroup,
                int            mcastport,
                const char    *dcppath)

DESCRIPTION

lgmp_init() is used to create and instantiate an LGMP endpoint repesented by an LGMP context. It allows the user to configure the characteristics of this LGMP endpoint. lgmp_init() is used to instantiate LGMP contexts for both multicast receivers and multicast senders.
The lgmp_init() function  takes four arguments.

init	is a pointer to an lgmp_init_t structure. If the init pointer is Null the LGMP context is initialized with default values.
mcastgroup	is the name of the multicast group (class D IP address in dotted form)
mcastport	is the port number of this multicast group
dcppath	is the pathname of the associated DCP (Dynamic Configuration Protocol) program. If the dcppath argument is Null "./dcp" is used instead.

The lgmp_init_t data type is used to configure the newly created LGMP context. The data type has the following fields:
 

unsigned short lgmp_options
unsigned char  lgmp_type
unsigned char  lgmp_retransmode
unsigned char  lgmp_ttl
int            lgmp_maxmtusize
int            lgmp_maxmembernum
long           lgmp_maxrate
long           lgmp_maxburst
long           lgmp_maxsndwindow
long           lgmp_maxsndbufsize
unsigned char  lgmp_checksum

The user fills in certain fields in the lgmp_init_t structure and uses lgmp_options flags to indicate which fields have valid entries. For all unspecified fields the default values for these fields are taken. The lgmp_optons field holds the logical OR of any of the following flags:

LGMP_TYPE	defines the type of the newly created LGMP context. Three initial values are allowed:    LGMP_SENDER     LGMP_RECEIVER         (default value)     LGMP_GROUPCONTROLLER  During the data transfer the context type can change from LGMP_RECEIVER to LGMP_GROUPCONTROLLER or from LGMP_GROUPCONTROLLER to LGMP_RECEIVER initiated by the DCP. However the definition as LGMP_SENDER remains unchanged during the communication. Such a type change is totally transparent for the user. Normally a user doesn't need to configure a context as LGMP_GROUPCONTROLLER except for ISPs or for static tests.
LGMP_RETRANSMODE	is used to define the way how LGMP performing local retransmissions. There are two modes:    LGMP_LOADSENSITIVE     (default value)    LGMP_DELAYSENSITIVE    (currently not implemented)  The load sensitive mode optimizes network load and the delay sensitive mode optimizes network delay.
LGMP_TTL	is used to restrict the range of the multicast group. The default value is 64.
LGMP_MAXMTUSIZE	defines the maximum size of an LGMP-MTU (Message Transfer Unit). It is the maximum length of  the payload area in an LGMP data packet. The default value is 1462 Bytes. For the use in the current MBone without IP fragmentation the sender and the receivers  has to use a maximum MTU-size of 1442 Bytes.
LGMP_MAXMEMBERNUM	defines the maximum number of local group members. the default value is 30. In the current implementation this parameter value has to be less then 64.  When the context type is defined as LGMP_RECEIVER and the user doesn't want that this context would be able to become a local group controller the user can fill this parameter with 0.
LGMP_MAXRATE  (sender specific)	defines the data rate in Bytes per sec. This parameter is one part of LGMP's rate control.  The user can disable the rate control by using a special parameter value:    LGMP_NORATE            (default value)  The use of this value is only advisable when the user performs his own rate control.
LGMP_MAXBURST  (sender specific)	defines the burst length in Bytes. This is the other part of LGMP's rate control. The default burst length is 1462 Bytes.
LGMP_MAXSNDWINDOW  (sender specific)	defines the maximum amount of data in kBytes that can be placed in LGMP context's internal send buffer without receiving acknowledges. It is the size of the flow control window.  The user can disable the flow control by using a special value for this parameter    LGMP_NOWINDOW          (default value)
LGMP_MAXSNDBUFSIZE  (sender specific)	this parameter defines the amount of data in kBytes that is held in the send buffer although all group members have received these data correctly. This is necessary for so called Late comers that join a multicast group after the sender has started to send. This part of the send buffer is not a part of the flow control window. THe default value is defined as 10% of the current flow control window size.
LGMP_CHECKSUM  (sender specific)	if the user doesn't want to protect the user data (payload) with a checksum the user specify LGMP_NOCHECK, otherwise LGMP_USECHECK. LGMP_USECHECK is the default value.

 

Note:
 

• There exists currently no standardized mechanism for generating automatically temporal multicast addresses that are need by nearly all LGMP contexts. Therefore all LGMP contexts (except plain LGMP_RECEIVERs whose lgmp_maxmembernum is 0) read such an address to use as local group address from a file ("./mclocaladdr"). An LGMP context need an own  local group address when it is or become group controller. This address is the address of the managed local group. The file mclocaladdr has to be in the current directory and consists only of an IP multicast address (in dotted form) followed by a port number. In future when there is standard method available the file mclocaladdr will become superfluous.
 

 RETURN VALUES

lgmp_init() returns a value >= 0 on success. In this case the return value is the LGMP context descriptor of the newly created LGMP context. This context descriptor is used by lgmp_receive(),  lgmp_send() , lgmp_sendstatus() , lgmp_end() and lgmp_abort() to access a specific LGMP context.
On error lgmp_init() returns -1 and prints out to standard error (stderr) a textual error message.
 

EXAMPLES

• creates an LGMP context with default values for all fields of lgmp_init_t. This context is a initialized as multicast receiver.

int descr;
descr = lgmp_init( NULL, "229.1.1.1", 6666, "./dcp");
.....
 

• creates an LGMP context for a multicast sender, with rate control (30000 Bytes/sec), specified burst length (3000 Bytes), MTU-size (1442 Bytes) , send window (2000 kBytes) and a TTL value of 128:

lgmp_init_t   init;
int           descr;
init.lgmp_type         = LGMP_SENDER;
init.lgmp_ttl          = 128;
init.lgmp_maxmtusize   = 1442;
init.lgmp_maxrate      = 30000;
init.lgmp_maxburst     = 3000;
init.lgmp_maxsndwindow = 2000;
init.lgmp_options      = LGMP_TYPE | LGMP_TTL | LGMP_MAXMTUSIZE | LGMP_MAXRATE | LGMP_MAXBURST | LGMP_MAXSNDWINDOW;
descr = lgmp_init( &init, "229.1.1.1", 6666, "./dcp");
.....

SEE ALSO

example LGMP receiver application (lgmp_receiver.c)
example LGMP sender application (lgmp_sender.c)
 

NAME

lgmp_send - LGMP user data send

SYNOPSIS

#include "lgmp.h"

int  lgmp_send( int                    ctx_descr,
                const void            *buf,
                int                    buflen,
                const struct timeval  *timeout)    /* new in Version 2.0 */

DESCRIPTION

Once a user instantiates an LGMP context (see lgmp_init() ) as multicast sender, the user may send data (messages) to all other LGMP endpoints associated with this LGMP context's multicast group. The lgmp_send() function takes four arguments:

 

ctx_descr	is an unique LGMP context descriptor. It identifies the LGMP context (it has to be a sender context). .
buf	is a pointer to a buffer containing data (message) to be sent to the group.
buflen	is the number of bytes to send
timeout	is used to define a maximum timeout period where lgmp_send() will block. lgmp_send() blocks only if the specified end of the send window is reached (LGMP_MAXSNDWINDOW ), in case of a full internal send buffer. It blocks as long as it is not possible to place the complete user data into the send buffer or the timeout period has expired.  If the timeout parameter is {0,0} lgmp_send() returns immediately; lgmp_send() operates as a non blocking function (this was exactly the behavior of lgmp_send() in LGMP versions 1.0, 10a and 1.1)  If the timeout parameter is NULL lgmp_send() will block only if the internal send buffer is full. It returns at the latest after expiration of the default timeout value (1000 sec)

lgmp_send() puts the user data in an internal send buffer and returns with the number of bytes placed in this send buffer as return value. When the user data is completely placed in the send buffer the last created LGMP data packet of this user message gets set the EOM (End of Message) bit. So LGMP receivers working in message mode (LGMP_MSGMODE) can detect message boundaries (see lgmp_receive() ).

During the waiting period (specified by the timeout parameter) the user may call pthread_cancel() to cancel the thread performing the lgmp_send() operation. After cancellation of lgmp_send() the user is allowed to call lgmp_send() again, lgmp_end() or lgmp_abort()
 
Note:

For getting the same behavior of lgmp_send() as in version 1.0, 10a and 1.1 replace your old lgmp_send() call
                    lgmp_send( ctx_descr, &buf, buflen);
 
with the following lines:
 
                    struct timeval  zero_tv = {0,0};
                    lgmp_send( ctx_descr, &buf, buflen, &zero_tv);
 

RETURN VALUES

>= 0	the number of bytes placed in send buffer. The return value is always <= buflen.
-1	an error occurred, lgmp_send() prints also an error message out to standard error (stderr)

 

 SEE ALSO

example LGMP sender application (lgmp_sender.c)
 

NAME

lgmp_sendstatus - LGMP send status

SYNOPSIS

#include "lgmp.h"

int  lgmp_sendstatus( int            ctx_descr,
                      int            *retflags)
 

DESCRIPTION

Once a user instantiates an LGMP context (see lgmp_init() ) as multicast sender, the user may send data (see  lgmp_send() ) to all other LGMP endpoints associated with this LGMP context's multicast group. The user may also use lgmp_sendstatus(), which returns the current status of the lgmp internal send buffer (send window).
 lgmp_sendstatus() function takes two arguments:

ctx_descr	is an unique LGMP context descriptor. It identifies the LGMP context (it has to be a sender context). .
retflags	The following bit flags are returned through retflags  LGMP_SENDEMPTY : there is nothing to send (the internal send buffer is empty)  LGMP_SENDACTIVE: current send buffer is partially full (the end of the send window is not reached).  LGMP is active, which means that LGMP is sending (and/or retransmitting) data to the context's multicast group. LGMP_SENDFULL  : end of current send window is reached (the internal send buffer is full). LGMP is sending (and/or retransmiting) data to the context's multicast group.

 
 

RETURN VALUES

= 0	operation was successful.
-1	an error occurred, lgmp_sendstatus() prints also an error message out to standard error (stderr)

 

NAME

lgmp_receive - LGMP user data receive

SYNOPSIS

#include "lgmp.h"

int  lgmp_receive( int                   ctx_descr,
                   void                 *buf,
                   int                   buflen,
                   int                   mode,
                   const struct timeval *timeout,
                   int                  *retflags)

 DESCRIPTION

Once a user instantiates an LGMP context (see lgmp_init() ) as multicast receiver (or group controller), the user may attempt to get received multicast data from the context. The lgmp_receive() function takes four arguments:

 

ctx_descr	is an unique LGMP context descriptor. It identifies the LGMP context (it has to be a receiver or group controller context). .
buf	is a pointer to a user buffer where the LGMP context puts in the received multicast data which is deliverable.
buflen	as many as buflen Bytes may be placed into the user buffer (buf)
mode	defines the data delivery policy. There are two modes:    LGMP_STREAMMODE    LGMP_MSGMODE  In LGMP_STREAMMODE the user data of every incoming LGMP data packet with a continuous sequence number is deliverable (continuous stream of user data). In LGMP_MSGMODE the received multicast data is deliverable when the complete message where this data contains of is arrived  The end of a message is indicated by the EOM flag in the received data packet..
timeout	is used to define a maximum timeout period where lgmp_receive() will block. lgmp_receive() blocks only if no deliverable received data (defined by data delivery policy) is present  If the timeout parameter is {0,0} lgmp_receive() returns immediately; lgmp_receive() operates as a non blocking function  If the timeout parameter is Null lgmp_receive() will block only if no deliverable data is present. It returns after expiration of the default timeout value (1000 sec)
retflags	The following bit flags are returned through retflags  LGMP_EOM : the last part of a message is delivered, only in LGMP_MSGMODE. In LGMOP_STREAMMODE this flag isn't used.  LGMP_END : the regular end of the LGMP data transfers reached, the user has to call lgmp_end() or lgmp_abort() for terminating this LGMP context.  LGMP_TIMEOUT : the timeout period has expired and there was no received multicast data deliverable  LGMP_ERROR : there is an unrecoverable sequence number gap (because of a network partition for example), so the data that should be delivered can't be placed in the user buffer. When the user call lgmp_receive() again LGMP tries to deliver received multicast data that follows this gap.

 
lgmp_receive() is defined as an explicit cancellation point. During the waiting period (specified by the timeout parameter) the user may call pthread_cancel() to cancel the thread performing the lgmp_receive() operation. After cancellation of lgmp_receive() the user is allowed to call lgmp_receive() again, lgmp_end() or lgmp_abort()

RETURN VALUES

>= 0	the number of bytes placed in the user buffer (buf). The return value is always <= buflen. Also a bit wise combination of the flags (LGMP_EOM, LGMP_END, LGMP_TIMEOUT, LGMP_ERROR) is returned through retflags. If none of the bit flags is true then 0 is returned through retflags
-1	an internal error (no communication error) occurred, lgmp_receive() prints also an error message out to standard error (stderr)

 

SEE ALSO

example LGMP receiver application (lgmp_receiver.c)

 

NAME

lgmp_end - normal LGMP context termination

SYNOPSIS

#include "lgmp.h"

int  lgmp_end(  int    ctx_descr)

 DESCRIPTION

After a user instantiated a LGMP context (see lgmp_init() ) and the user has finished using that context, the user has release the resources being held to support the LGMP endpoint represented by this context. lgmp_end() terminates the specified LGMP context, releases the resources, IPC-facility, closes all open sockets and terminates the associated DCP process.
When this LGMP context is a sender or group controller context the call lgmp_end() returns until this LGMP endpoint has no active local group members and all used resources are released.  Therefore lgmp_end() is defined as an explicit cancellation point. During this waiting period the user may call pthread_cancel() to cancel the thread performing the lgmp_end() operation. After cancellation of lgmp_end() the user is only allowed to call lgmp_abort() or lgmp_end() once again.

RETURN VALUES

When this function finishes successfully lgmp_end() returns 0, and -1 on failure. On failure lgmp_end() prints also out an error message to stderr.

SEE ALSO

example LGMP receiver application (lgmp_receiver.c)
example LGMP sender application (lgmp_sender.c)
 

NAME

lgmp_abort - abrupt LGMP context termination

SYNOPSIS

#include "lgmp.h"

int  lgmp_abort( int    ctx_descr)

DESCRIPTION

After a user has instatiated a LGMP context (see lgmp_init()) and the user wants to finish immediately this LGMP endpoint the user has to call lgmp_abort(). lgmp_abort() terminates immediately (without waiting, see lgmp_end() ) the specified LGMP context (ctx_descr), releases all used resources (IPC-facility, sockets, ...) and terminates the associated DCP process (see lgmp_init() ).

RETURN VALUES

When this function finishes successfully lgmp_abort() returns 0, and -1 on failure. On failure lgmp_abort() prints also out an error message to stderr.

 SEE ALSO

example LGMP receiver application (lgmp_receiver.c)
example LGMP sender application (lgmp_sender.c)