emcast protocol by David Helder Copyright (C) 2001 Regents of the University of Michigan ============================================================ A program is compiled with libemcast. Libemcast communicates with an emcast handler using the emcast protocol over two streams, the control stream and the data stream. The control stream is two-way and the data stream one-way from handler to libemcast. See the diagram below. For example, the handler might be a child process, the control stream two pipes, and the data stream a FIFO. +---------------------+ stream-ctrl +---------+ | program | libemcast | <----> | handler | +---------------------+ <---- +---------+ stream-data Libemcast sends requests and receives responses from the handler using the control stream. The handler sends requests using the data stream. The handler can not receive responses using the data stream. If only one stream were used and both libemcast and the handler sent a request, each would think the other's request was a response to its own request, and a malfunction may occur. Using two streams seems the best solution. A short is two bytes. A long is four bytes. All integers are in network byte order. A message summary is below. INIT, JOIN, LEAVE, SEND, GETOPT, and SETOPT are sent from libemcast to the handler over the control stream. RECV is sent from the handler to libemcast over the data stream. INIT ---- libemcast sends an INIT message after the connection is established. This provides basic version negotiation. libemcast -> handler INIT 0x0000 short VERSION 0x0001 short FIFO_LENGTH short FIFO FIFO_LENGTH bytes handler <- libemcast RESPONSE 0 on success byte non-0 on falure VERSION 0x0001 short libemcast sends the highest version it supports. handler returns highest version it supports and must be less than or equal to the highest version libemcast supports. The version the handler returns is the version used. This document describes version 1. The FIFO is created by libemcast. Each side will open it for reading and writing after the initialization sequence. [If we were to support the protocol over sockets, this would need to change.] JOIN ---- libemcast sends a JOIN message to join a multicast group. A group is either created or joined. Only one group can be created or joined. libemcast -> handler ID 0x0001 or 0x0002 short URL_LENGTH length of URL unsigned short URL URL URL_LENGTH bytes hander -> libemcast RESPONSE 0 on success byte non-0 on failure LEAVE ----- libemcast sends a LEAVE message to leave the group. libemcast must close the connection after receiving the response. The handler must close the connection after sending the response. libemcast -> handler ID 0x0003 short handler -> libemcast RESPONSE 0 on success byte non-0 on failure SEND ---- libemcast send a SEND message to send multicast data. Delivery is assumed to be best-effort. The handler should return a response immediately. libemcast -> handler ID 0x0005 short LENGTH length of DATA unsigned short DATA data LENGTH bytes handler -> libemcast RESPONSE 0 on success byte non-0 on failure RECV ---- handler -> libemcast ID 0x0006 short LENGTH length of DATA unsigned short FROM_LEN length of FROM unsigned short DATA data LENGTH bytes FROM from FROM_LEN bytes RECV's are sent over the second stream. libemcast does not respond to the handler. GETOPT ------ libemcast -> handler ID 0x0007 short NAME_LEN length of NAME unsigned short NAME name of option NAME_LEN bytes handler -> libemcast RESPONSE 0 on success, byte 1 if bad option X on failure VAL_LEN length of VAL unsigned short VAL value of option VAL_LEN bytes VAL_LEN/VAL isn't sent if RESPONSE is non-zero. SETOPT ------ libemcast -> handler ID 0x0007 short NAME_LEN length of NAME unsigned short VAL_LEN length of VAL unsigned short NAME name of option NAME_LEN bytes VAL value of option VAL_LEN bytes handler -> libemcast RESPONSE 0 on success, byte 1 if bad option 2 if bad value