From 190665fe57168a4b9d544b88d3f69797f258c04c Mon Sep 17 00:00:00 2001 From: "E. Scott Daniels" Date: Mon, 9 Dec 2019 09:05:22 -0500 Subject: [PATCH] Correct documentation for MEID The MEID acronym was incorrectly documented as "managed equipment" and not "manage entity". This change fixes this. The RTD relase nodes were not being updated from the change log in the repo root, and thus were not updated on the RTD site. This change adds the needed Makefile changes to ensure that all generated docs for RTD are updated and published. Signed-off-by: E. Scott Daniels Change-Id: I2e3d741451221211a8abe49b7eca70dd6f935cbb --- CHANGES | 3 +++ CMakeLists.txt | 2 +- doc/src/man/rmr.7.xfm | 30 ++++++++++++++++++------------ doc/src/man/rmr_bytes2meid.3.xfm | 2 +- doc/src/man/rmr_get_meid.3.xfm | 2 +- doc/src/man/rmr_str2meid.3.xfm | 2 +- doc/src/rtd/Makefile | 25 +++++++++++++++++++++++-- docs/overview.rst | 14 ++++++++++---- docs/rel-notes.rst | 32 ++++++++++++++++++++++++++++++-- docs/user-guide.rst | 8 ++++---- src/rmr/common/src/mbuf_api.c | 2 +- 11 files changed, 93 insertions(+), 29 deletions(-) diff --git a/CHANGES b/CHANGES index 890a1a2..11264c5 100644 --- a/CHANGES +++ b/CHANGES @@ -2,6 +2,9 @@ API and build change and fix summaries. Doc correctsions and/or changes are not mentioned here; see the commit messages. +2019 December 9; version 1.13.1 + Correct documentation and missing rel-notes update for RTD. + 2019 December 6; version 1.13.0 Add ability to route messages based on the MEID in a message combined with the message type/subscription-ID. diff --git a/CMakeLists.txt b/CMakeLists.txt index 6f5a78c..a755c1b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -36,7 +36,7 @@ cmake_minimum_required( VERSION 3.5 ) set( major_version "1" ) # should be automatically populated from git tag later, but until CI process sets a tag we use this set( minor_version "13" ) -set( patch_level "0" ) +set( patch_level "1" ) set( install_root "${CMAKE_INSTALL_PREFIX}" ) set( install_inc "include/rmr" ) diff --git a/doc/src/man/rmr.7.xfm b/doc/src/man/rmr.7.xfm index ae49977..70f55af 100644 --- a/doc/src/man/rmr.7.xfm +++ b/doc/src/man/rmr.7.xfm @@ -94,28 +94,28 @@ and by supplying a "table" such as the one below: &ex_start meid_map | start mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 - mme_ar | control2 | meid100 meid101 meid102 meid103 + mme_ar | control2 | meid100 meid101 meid102 meid103 meid_map | end | 2 &ex_end This table indicates that the application (endpoint) &ital(control1) "owns" 6 MEIDs -and &ital(control2) owns 4. -When message type 0 is sent, the MEID in the message will be used to select the -endpoint via this table. +and &ital(control2) owns 4. +When message type 0 is sent, the MEID in the message will be used to select the +endpoint via this table. &space The MEID table will update the existing owner relationships, and add new ones; it is necessary to send only the changes with the add/replace (mme_ar) entries in -the table. +the table. When necessary, MEIDs can be deleted by adding an &cw(mme_del) record to the table. The following example illustrates how this might look: &ex_start meid_map | start mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 - mme_ar | control2 | meid100 meid101 meid102 meid103 + mme_ar | control2 | meid100 meid101 meid102 meid103 mme_del| meid200 meid401 -meid_map | end | 1 +meid_map | end | 3 &ex_end &h3(Route Table Syntax) @@ -129,15 +129,15 @@ newrt | end &ex_end &space A round robin group is one or more endpoints from which one will be selected to receive -the message. +the message. When multiple endpoints are given in a group, they must be separated with a comma. An endpoint is the IP address and port (e.g. 192.158.4.30:8219) or DNS name and port of the application that should receive the message type. -If multiple round-robin groups are given, they must be separated by a semicolon, and +If multiple round-robin groups are given, they must be separated by a semicolon, and &h3(MEID Map Syntax) -The MEID map is similar to the route table. -Entries are used to add or replace the ownership of one or more MEIDs (mme_ar) or to +The MEID map is similar to the route table. +Entries are used to add or replace the ownership of one or more MEIDs (mme_ar) or to delete one or more MEIDs (mme_del). The following is the syntax for the MEID map. @@ -146,7 +146,7 @@ The following is the syntax for the MEID map. meid_map | start mme_ar | | [...] mme_del | [...] -meid_map | end | +meid_map | end | [| &ex_end &space @@ -158,6 +158,12 @@ A MEID may be "owned" by only one endpoint, and if supplied multiple times, the observed relationship is used. Each of the lists of MEIDs are blank separated. +&space +The optional on the &ital(end) record should be the computed MD5 hash for all +records which appear between the start and and records. +This allows for a tighter verification that all data was received exactly as the +route manager transmitted them. + &h3(Environment) To enable configuration of the library behaviour outside of direct user application diff --git a/doc/src/man/rmr_bytes2meid.3.xfm b/doc/src/man/rmr_bytes2meid.3.xfm index 86cee72..7332c7b 100644 --- a/doc/src/man/rmr_bytes2meid.3.xfm +++ b/doc/src/man/rmr_bytes2meid.3.xfm @@ -45,7 +45,7 @@ int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len ) &h2(DESCRIPTION) The &cw(rmr_bytes2meid) function will copy up to &ital(len) butes from &ital(src) to the -managed equipment ID (meid) field in the message. +managed entity ID (meid) field in the message. The field is a fixed length, gated by the constant &cw(RMR_MAX_MEID) and if len is larger than this value, only RMR_MAX_MEID bytes will actually be copied. diff --git a/doc/src/man/rmr_get_meid.3.xfm b/doc/src/man/rmr_get_meid.3.xfm index d31bb3c..39fcafd 100644 --- a/doc/src/man/rmr_get_meid.3.xfm +++ b/doc/src/man/rmr_get_meid.3.xfm @@ -44,7 +44,7 @@ char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest ) &uindent &h2(DESCRIPTION) -The &cw(rmr_get_meid) function will copy the managed equipment ID (meid) field from the message +The &cw(rmr_get_meid) function will copy the managed entity ID (meid) field from the message into the &ital(dest) buffer provided by the user. The buffer referenced by &ital(dest) is assumed to be at least &cw(RMR_MAX_MEID) bytes in length. If &ital(dest) is NULL, then a buffer is allocated (the calling application is expected diff --git a/doc/src/man/rmr_str2meid.3.xfm b/doc/src/man/rmr_str2meid.3.xfm index 28f85c6..c646c28 100644 --- a/doc/src/man/rmr_str2meid.3.xfm +++ b/doc/src/man/rmr_str2meid.3.xfm @@ -45,7 +45,7 @@ int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len ) &h2(DESCRIPTION) The &cw(rmr_str2meid) function will copy the string pointed to by src to the -managed equipment ID (meid) field in the given message. +managed entity ID (meid) field in the given message. The field is a fixed length, gated by the constant &cw(RMR_MAX_MEID) and if string length is larger than this value, then &bold(nothing) will be copied. (Note, this differs slightly from the behaviour of the &cw(lrmr_bytes2meid()) function.) diff --git a/doc/src/rtd/Makefile b/doc/src/rtd/Makefile index 4c64278..a714e6a 100644 --- a/doc/src/rtd/Makefile +++ b/doc/src/rtd/Makefile @@ -36,11 +36,20 @@ docs = config-deploy developer-guide user-guide rel-notes overview -all:: $(docs:%=%.rst) $(docs:%=%.txt) $(docs:%=%.md) +all:: $(docs:%=%.rst) $(docs:%=%.txt) $(docs:%=%.md) -rel-notes.xfm: +rel-notes.xfm: ../../../CHANGES ksh fmt_changes.ksh >rel-notes.xfm +# we force the docs to always be out of date so that we don't have to +# manage the list of man pages and other files that are read to generate the +# output needed for RTD. +# +$(docs:%=%.rst): always +$(docs:%=%.txt): always +$(docs:%=%.md): always + + # copy the .rst files which have changed into the docs (plural) directory at the root of the repo publish : $(docs:%=%.rst) for f in *.rst;\ @@ -51,6 +60,16 @@ publish : $(docs:%=%.rst) fi;\ done +# just list what would be published +verify : $(docs:%=%.rst) + for f in *.rst;\ + do\ + if ! diff -N -q $$f ../../../docs/$$f >/dev/null 2>&1;\ + then\ + echo "$$f would be published";\ + fi;\ + done + # ditch any intermediate files clean: rm -f rel-notes.xfm *.sp *.ca @@ -59,3 +78,5 @@ clean: nuke: clean rm -f *.ps *.pdf *.rst *.md +# make hack to force a rule to always be out of date +always: diff --git a/docs/overview.rst b/docs/overview.rst index d382e69..e29b633 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -88,7 +88,7 @@ as the one below: meid_map | start mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 - mme_ar | control2 | meid100 meid101 meid102 meid103 + mme_ar | control2 | meid100 meid101 meid102 meid103 meid_map | end | 2 @@ -108,9 +108,9 @@ might look: meid_map | start mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 - mme_ar | control2 | meid100 meid101 meid102 meid103 + mme_ar | control2 | meid100 meid101 meid102 meid103 mme_del| meid200 meid401 - meid_map | end | 1 + meid_map | end | 3 @@ -151,7 +151,7 @@ the syntax for the MEID map. meid_map | start mme_ar | | [...] mme_del | [...] - meid_map | end | + meid_map | end | [| @@ -164,6 +164,12 @@ contains. A MEID may be "owned" by only one endpoint, and if supplied multiple times, the last observed relationship is used. Each of the lists of MEIDs are blank separated. +The optional on the *end* record should be the +computed MD5 hash for all records which appear between the +start and and records. This allows for a tighter verification +that all data was received exactly as the route manager +transmitted them. + Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/rel-notes.rst b/docs/rel-notes.rst index 01adf5b..35c181f 100644 --- a/docs/rel-notes.rst +++ b/docs/rel-notes.rst @@ -15,20 +15,48 @@ file at the repo root; please refer to that file for a completely up to date listing of API changes. -2019 November 14; version 1.11.1 +2019 December 9; version 1.13.1 +-------------------------------------------------------------------------------------------- + +Correct documentation and missing rel-notes update for RTD. + + +2019 December 6; version 1.13.0 +-------------------------------------------------------------------------------------------- + +Add ability to route messages based on the MEID in a message +combined with the message type/subscription-ID. + + + +2019 November 14; version 1.11.1 (Amber) -------------------------------------------------------------------------------------------- Fix bug in payload reallocation function; correct length of payload was not always copied. -2019 November 4; version 1.11.0 +2019 November 13; version 1.12.1 +-------------------------------------------------------------------------------------------- + +New message type constants added to support A1. + + +2019 November 4; version 1.11.0 (Amber) -------------------------------------------------------------------------------------------- Version bump to move away from the 1.10.* to distinguish between release A and the trial. +2019 November 7; version 1.12.0 +-------------------------------------------------------------------------------------------- + +Version cut to support continued development for next release +preserving the 1.11.* versions for release 1 (Amber) and +related fixes. + + 2019 October 31; version 1.10.2 -------------------------------------------------------------------------------------------- diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 6fc6e20..ad62076 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -204,8 +204,8 @@ DESCRIPTION -------------------------------------------------------------------------------------------- The rmr_bytes2meid function will copy up to *len* butes from -*src* to the managed equipment ID (meid) field in the -message. The field is a fixed length, gated by the constant +*src* to the managed entity ID (meid) field in the message. +The field is a fixed length, gated by the constant RMR_MAX_MEID and if len is larger than this value, only RMR_MAX_MEID bytes will actually be copied. @@ -689,7 +689,7 @@ SYNOPSIS DESCRIPTION -------------------------------------------------------------------------------------------- -The rmr_get_meid function will copy the managed equipment ID +The rmr_get_meid function will copy the managed entity ID (meid) field from the message into the *dest* buffer provided by the user. The buffer referenced by *dest* is assumed to be at least RMR_MAX_MEID bytes in length. If *dest* is NULL, @@ -2786,7 +2786,7 @@ DESCRIPTION -------------------------------------------------------------------------------------------- The rmr_str2meid function will copy the string pointed to by -src to the managed equipment ID (meid) field in the given +src to the managed entity ID (meid) field in the given message. The field is a fixed length, gated by the constant RMR_MAX_MEID and if string length is larger than this value, then **nothing** will be copied. (Note, this differs slightly diff --git a/src/rmr/common/src/mbuf_api.c b/src/rmr/common/src/mbuf_api.c index c879d7c..84996ee 100644 --- a/src/rmr/common/src/mbuf_api.c +++ b/src/rmr/common/src/mbuf_api.c @@ -239,7 +239,7 @@ extern unsigned char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest ) { } /* - Extracts the meid (managed equipment) from the header and copies the bytes + Extracts the meid (managed entity) from the header and copies the bytes to the user supplied area. If the user supplied pointer is nil, then a buffer will be allocated and it is the user's responsibilty to free. A pointer is returned to the destination memory (allocated or not) -- 2.16.6