SRMP API Document

All functions, type and macro definitions needed to use the SRMP API are included in your code by the following line:

#include "srtp_api.h"

 

Before any other SRMP API function is called, srmp_init( ) must be called first.

Before srmp_send( ) is called to send out a mode 1 message, the dataid of the outgoing mode 1 message must have been  registered beforehand by calling srmp_reg_dataid( ). However, there is no such necessary for a mode 0 message.

Before calling srmp_recv( ), the application must call srmp_subscribe_mca( ) to subscribe traffic that belong to a specific multicast group or groups.

 

int srmp_init( int udp_port ):

Description: Initialize data structures for inter process communication between Application and SRMP daemon.

      Note: this function must be called before any other SRMP API function.

Parameters:

int udp_port: the port number that local SRMP daemon is listening on for client request. If udp_port == 0, default value will be used, which is 8001.

Returns:

0 – Success

1 – Fail

 

int  srmp_reg_dataid(unsigned long int mca, int dataid, int mode)

Description: register a <multicast_address, dataid, mode> to the SRMP dameon. A dataid is unique in the client’s host within a multicast group.

Before a mode 1 message can be sent out, the dataid of the mode 1 message must be registered first. There is no necessary to register a dataid before sending out a mode 0 message.

 The mode of a dataid is fixed after being registered. To change the mode, the dataid must first be un-registered, and then registered again. A registration to a dataid will fail, if the dataid has already been registered before. A client can send out messages of the dataid that was registered by other clients.

      After a dataid has been registered, the application can start to send out mode 1 message with the corresponding dataid.

If called with mode == 0, this function will do nothing but simply return 0;

Mode 2 is not supported in this version.

Parameters:

unsigned long int mca – the multicast group address that the dataid belongs to

int dataid – the dataid to be registered

int mode – the mode that the dataid should be delivered with, either 0 or 1

Returns:

0 – Success

1 – Fail

 

int  srmp_unreg_dataid(unsigned long int mca, int dataid)

Description: un-register a dataid that has been registered. SRMP will remove the dataid from the internal table. After being un-registered, message of the un-registered dataid will not be able to sent out anymore.

Parameters:

unsigned long int mca -- the multicast group address that the dataid belongs to

int dataid – the dataid to be un-registered

Returns:

0 – Success

1 – Fail

 

int srmp_send(char *data, int len,  int dataid, unsigned long int mca)

Description: send out message to the multicast group.

      Note: The SRMP daemon will try to send the message to all other local clients that have subscribed the group, as well as send it out to the network. The SRMP will not loop back the message to the sending client.

Parameters:

char * data – the message body to be sent out

int len – the length of the message

int dataid – the dataid of the message to be sent out

unsigned long int mca – the multicast group address that the dataid belongs to

 

Returns:

0 – Success

1 – Fail

 

int srmp_subscribe_mca(unsigned long int mca)

Description: subscribe a multicast group. The client must call this function before srmp_recv( ) to be able to receive all the traffic of the multicast group.

Parameters:

unsigned long int mca – the multicast group address to be subscribed

Returns:

0 – Success

1 – Fail

 

int srmp_unsubscribe_mca(unsigned long int mca )

Description: un-subscribe a multicast group. After un-subscribe, the SRMP daemon will stop sending traffic of the specified multicast group to the client.

Parameters:

unsigned long int mcg – the multicast group address to be un-subscribed

Returns:

0 – Success

1 – Fail

 

 

int srmp_recv(char *buf, int *len, int *dataid, unsigned long int *mca)

Description: receive message from local SRMP daemon. When call this function, the client will be blocked until a message is received

Parameters:

char * buf – the buffer that contains the received message. The buffer memory should be allocated by the client application before calling the function. The buffer length should be larger than 131099 bytes.

int * len – aftern the function return, the len will be the length of the message received.

int dataid – after the function returned,  the dataid will be the dataid of the message received. If dataid == 0, a mode 0 message has been just received.

 unsigned long int mca – the multicast group address that the dataid belongs to

Returns:

0 – Success

1 – Fail