2 --------------------------------------------------------------------------------
4 Copyright (c) 2018-2019 AT&T Intellectual Property.
6 Licensed under the Apache License, Version 2.0 (the "License");
7 you may not use this file except in compliance with the License.
8 You may obtain a copy of the License at
10 http://www.apache.org/licenses/LICENSE-2.0
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 See the License for the specific language governing permissions and
16 limitations under the License.
17 --------------------------------------------------------------------------------
23 This directory contains the source for the a simple message listener which
24 writes messages received via RMR into a fifo (named pipe) for an external
27 Fifos are named MT_xxxxxxxx where the Xs are replaced with the message
28 type with up to 7 leading zeros (e.g. MT_00000002). The data written
29 to a pipe has the form:
32 Where the first 8 bytes are the ASCII representation of the length of
33 the message (n) (the 8th byte is a zero allowing the bytes to be
34 treated as a C string if desired. The next n bytes are the unchanged
35 payload which was received. No RMR header information (e.g. source,
36 meid, etc.) is communicated.
38 If the listener is executed with the timestamp extension enabled, then
39 the leading 'header' is enhanced such that the time the message was
40 received by the listener is added. Additionally, a leading delimiter
41 is added to make synchronisation possible. The timestamp is also an
42 ASCII string of the form 1570110224356 (milliseconds past the epoch).
43 The enhanced header has the format:
45 <delimeter><length-bytes><time-bytes>
47 The <delimeter> is a series of 4 bytes which should always be: '@MCL'.
48 It is intended to be used to sequence "frames" in the pipe should there be
49 write errors which result in missing data. If the application reading from
50 a pipe does not see this delimeter, then it should read byte by byte from
51 the pipe until it does in order to synchronise with the stream.
53 The <length-bytes> are as descrbed previously: 8 byte ASCII string (nil
56 The <time-bytes> is an ASCII string (nil terminated) with a length of 16
59 The entire header will require 28 bytes.
62 There are multiple docker files; *.df.
63 mcl_runime.df -- builds an image with the runtime mc_listener binary
64 mcl_dev.df -- builds a development image that can be used to
65 interactively build and test the library and mc_listener
69 A very small set of unit tests are provided for the library functions in
70 mcl.c. Because of the nature of the fanout function, which blocks waiting
71 on RMR messages, it is not possible to unit test that bit of code.
74 The pipe_reader programme is a simple application which uses the mcl.c
75 library functions to open and read from a single pipe. If the -e option
76 is given it will expect that data in the FIFO has extended headers. Use
77 the -? option (or -h) to generate a full usage statement.