LGMP Programming Interface

(MS Windows Version 1.0)

This is the description for the MS Windows version of the LGMP (Local Group based Multicast Protocol) programming interface.
User application programs can use LGMP for exchanging data by dynamically or statically linking the LGMP library file (lgmp.dll or lgmpd.dll). To link the library to your application you only need the interface include file (lgmp.h) and the corresponding linker file (lgmp.lib or lgmpd.lib). 
Only lgmpd.dll supports debug output to stderr or a log file. It is build with debug infos and without compiler optimization to allow code-debugging. But you should only debug the following interface functions, because debugging the internal threads will conflict with the threads dependencies - use the logfile instead.
On the other hand lgmp.dll is optimized for speed and does not support debug message logging.
The dynamic link libraries were build with MS VC++ 5.0. However the *.lib files were created to allow linking with compilers/linkers of other vendors. ( I hope :-)) never tested yet - please let me know if you succeed or not).

If you want to write applications for several supported platforms, Unix-Versions and MS Windows, you should notice the following.
This MS Windows version 1.0 is the counterpart of the Unix version 2.0E of the LGMP protocol. But there exist some minor differences and restrictions for the MS Windows version.
There is a new function lgmp_init_log() and an additional timeout parameter in the lgmp_end() function. In addition, please notice that there is no Pthread like multithreaded library support under Windows, and you should avoid thread termination to stop blocking functions. Therefore lgmp_end() has an additional timeout parameter for MS Windows.
 
These are the calls that applications can use to interact with LGMP.

lgmp_init_log
lgmp_init
lgmp_send 
lgmp_sendstatus 
lgmp_receive
lgmp_end
lgmp_abort

Below is the description of these library calls
 

NAME

lgmp_init_log - LGMP logging initialisation 

SYNOPSIS

#include "lgmp.h"

int  lgmp_init_log( const char*      path_p,
                    unsigned short   debuglevel,
                    int              fullinit)

DESCRIPTION

This is a special function for the MS Windows version of LGMP, because there is no way to log stderr output except for commandline applications. The function can be called any time, but it should be called before the lgmp_init() function to be able to log the initialisation.
It creates the specified log file and writes all error and debug messages to that file, if the message level is selected by the debug level parameter.
There is only one log file for each application, so this function should be called only once to init the logfile. If you use multiple LGMP contexts, all are logged to the same log file.

path_p	is the pathname of the log file. If this is NULL then we log to stderr
debuglevel	specifies the debug level of the output that should be logged. This represents a bitmap which filters the debug messages with an AND operation.
fullinit	specifies wether or not this is a "full" initialisation. If fullinit = 1 the specified file is opened, otherwise only the debug level will be changed. ATTENTION: You have to initiate with fullinit = 1 first!

RETURN VALUES

1	everything OK (fullinit = 1 only).
0	the debug level is changed. If this was a full initialisation there was a file open error
-1	an error occurred (never initialized and fullinit = 0).

Back to TOC

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 does not want that this context to 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 does not 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:
 

• Currently no standardized mechanism exists  for generating automatically temporal multicast addresses that are needed 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"). A LGMP context needs a local group address of its own when it is or becomes 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 the future, when a standard method will be available, the file mclocaladdr will become superfluous.
  In this MS Windows version we implemented a random address generating function. If you do not specify a multicast address (no "mclocaladdr" file) we generate a random address. This should ease local testing if you have no information about locally used multicast addresses.

 RETURN VALUES

>= 0	means success. The returned 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.
-1	an error occurred. The error reason is logged.

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");
.....

Back to TOC

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)   

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 a 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  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() ).

RETURN VALUES

>= 0	the number of bytes placed in send buffer. The return value is always <= buflen, where < buflen means that the timeout has reached before sending all data.
-1	an error occurred, see debug output for details.

Back to TOC

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, see debug output for details.

Back to TOC

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 a 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 a 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() operates as a non blocking function and returns immediately. 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 is not 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 cannot 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, see debug output for details

Back to TOC

NAME

lgmp_end - normal LGMP context termination

SYNOPSIS

#include "lgmp.h"

int  lgmp_end( int                   ctx_descr,
                              const struct timeval  *timeout ) /* exist only in the MS Windows version */

 DESCRIPTION

After a user instantiated a LGMP context (see lgmp_init() ) and the user has finished using that context, the user has to 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 the LGMP context is a sender or group controller context, the lgmp_end() call normaly returns only after all local group members have left the local group. Because there is no chance to interrupt such a blocking function, we introduce the timeout parameter. After the timeout has reached the function will behave like lgmp_abort() and terminate the context regardless of actuell local group members. 

Please notice that for the server context the termination of context starts after sending at least one LGMP_END packet to the group members. If the sendbuffer is not empty, this will result in delayed termination. You can check the sendbuffer state with lgmp_sendstatus().

 

ctx_descr	is an unique LGMP context descriptor. It identifies the LGMP context.
timeval	specifies the maximum time to wait for group members to leave the local group before terminating the LGMP context.  If the timeout is a NULL pointer, then lgmp_end() waits  _LGMP_SENDER_MAXENDTIME (default 3 minutes) or  _LGMP_GC_MAXENDTIME (default 30 seconds). The receiver always ends immediatly; this parameter is ignored.

RETURN VALUES

0	everything is OK, all resources are freed
-1	an error occurred, see debug output for details

Back to TOC

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, he 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() ).

Please notice that for the server context the termination of context starts after sending at least one LGMP_END packet to the group members. If the sendbuffer is not empty, this will result in delayed termination. You can check the sendbuffer state with lgmp_sendstatus().

RETURN VALUES

0	everything is OK, all resources are freed
-1	an error occurred, see debug output for details

Back to TOC