diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 0d9f186..a0d3a54 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -58,6 +58,7 @@ else() add_manpage(owlps-client 1) add_manpage(owlps-listenerd 1) add_manpage(owlps-aggregatord 1) + add_manpage(owlps-udp-to-http 1) endif() diff --git a/doc/owlps-udp-to-http.t2t b/doc/owlps-udp-to-http.t2t new file mode 100644 index 0000000..fa5e614 --- /dev/null +++ b/doc/owlps-udp-to-http.t2t @@ -0,0 +1,128 @@ +Owl Positioning System UDP-to-HTTP +OwlPS {{OWLPS_VERSION}} +September 2013 + + +%%% +% Man title & section: +%!postproc(man): "^(\.TH.*) 1 " ".TH owlps-udp-to-http 1 " +% Fix .TH, add NAME section and TABLE OF CONTENTS title: +%!postproc(man): "^(\.TH.*)$" "\1 OwlPS\ User\ Manual\n.SH NAME\nowlps-udp-to-http - provide OwlPS results through HTTP" +% Man "links": +%!preproc(man): "(owlps)\.t2t" "//\1//(7)" +%!preproc(man): "(owlps-architecture)\.t2t" "//\1//(7)" +%!preproc(man): "(owlps-deployment)\.t2t" "//\1//(7)" +%!preproc(man): "(owlps-[^ ]*)\.t2t" "//\1//(1)" +%!preproc(man): "(owlps[^ ]*\.h)" "//\1//(3)" +%%% + + + + += Synopsis = + +**owlps-udp-to-http** [ **-v** | **-q** ] [ **-l** //result_port// ] [ **-t** //http_port// ] + + + + += Description = + +**OwlPS UDP-to-HTTP** receives results from OwlPS Positioner on a UDP +socket and allows a client to retrieve them with the HTTP protocol. Only +the last result received for a given mobile terminal is memorised and +provided to the HTTP client. The UDP socket listens on //result_port//, +which default value is the default port to which OwlPS Positioner sends +the results. The TCP (HTTP) socket listens on //http_port//. + +The client is expected to send an HTTP GET request, with a request +string as the first variable value (the variable's name does not +matter). For example, a correct request is detected if you load +http://localhost:8080/?request=ReadSimpleResults (assuming the host +running this program is localhost). + +The HTTP requests currently implemented are listed bellow. + + +== “ReadResults” request == + +Answer in case of error: +``` Results;NOK;Explanation + +``Explanation`` is "NoResult" if no results were received from OwlPS +Positioner yet. + +Normal answer: +``` Results;OK;Nb_results;Result_1;…;Result_n + +With: +- ``Nb_results``: the number of results in the answer (number of mobile + terminals). +- ``Result_i``: a result, following this format: +``` Mobile_MAC;Request_type;Request_timestamp;Nb_algo;Algo_1;…;Algo_n +- ``Nb_algo``: the number of algorithms in the result. +- ``Algo_i``: an algorithm, following this format: +``` Algorithm_name;X;Y;Z;Error;Area_name +- ``Error``: the distance from the true coordinates of the mobile, if + known; -1 if unknown. +- ``Area_name``: the name of the area or room in which the mobile is + (may be empty). + + +== “ReadSimpleResults” request == + +Answer in case of error: +``` SimpleResults;NOK;Explanation + +Normal answer: +``` SimpleResults;OK;Nb_results;Result_1;…;Result_n + +With: +- ``Nb_results``: the number of results in the answer (number of + mobile terminals). +- ``Result_i``: a result, following this format: +``` Mobile_MAC;X;Y;Z;Area_name +- ``Area_name``: the name of the area or room in which the mobile is + (may be empty). + + +== Unknown request == + +If a unknown request is received, the answer format is: +``` UnknownRequest;NOK + + + + += Options = + +: **-h** + Print help message and exit. +: **-V** + Print version information and exit. +: **-v** + Turn on verbose mode (default). +: **-q** + Do not print informational messages. +: **-l** //result_port// + Port on which the results are received (default: 9910). +: **-t** //http_port// + Port on which the HTTP server listens (default: 8080). + + + + += Copying = + +This documentation is part of the Owl Positioning System (OwlPS) +project. It is subject to the copyright notice and license terms +in the COPYRIGHT.t2t file found in the top-level directory of the +OwlPS distribution and at +http://code.lm7.fr/p/owlps/source/tree/master/COPYRIGHT.t2t + + + + += See also = + +owlps.t2t, owlps-positionerd.t2t diff --git a/owlps-udp-to-http/owlps-udp-to-http.c b/owlps-udp-to-http/owlps-udp-to-http.c index 0d0f3b7..f4c6f50 100644 --- a/owlps-udp-to-http/owlps-udp-to-http.c +++ b/owlps-udp-to-http/owlps-udp-to-http.c @@ -12,55 +12,9 @@ * *********************************************************************** * - * This is the main source file of OwlPS UDP-to-HTTP. - * - * This program listens for results sent by OwlPS Positioner on a UDP - * socket, and listens for a client on a TCP socket. The client is - * expected to send an HTTP GET request, with the request string as the - * first variable value (the variable name does not matter). - * For example, a correct request is detected if you load - * http://localhost:8080/?request=ReadSimpleResults - * (assuming the host running this program is localhost). - * - * The default UDP listening port is the port on which OwlPS Positioner - * sends the result by default, and the default TCP (HTTP) listening - * port is 8080. - * - * Only the last result read from the positioning server, for each - * mobile, is memorised and provided to the HTTP client. - * - * The HTTP requests currently implemented are listed bellow. - * - * ** Request "ReadResults" ** - * Answer in case of error: - * Results;NOK;Explanation - * Normal answer: - * Results;OK;Nb_results;Result_1;…;Result_n - * Nb_results is the number of results in the answer (number of mobiles). - * Result_i follows this format: - * Mobile_MAC;Request_type;Request_timestamp;Nb_algo;Algo_1;…;Algo_n - * Nb_algo is the number of algorithms in the result. - * Algo_i follows this format: - * Algorithm_name;X;Y;Z;Error;Area_name - * Error is the distance from the true coordinates of the mobile, if - * known; if unknown, Error is set to -1. - * Area_name is the name of the area or room in which the mobile is (may - * be empty). - * - * ** Unknown request ** - * If a unknown request is received, the answer format is: - * UnknownRequest;NOK - * - * ** Request "ReadSimpleResults" ** - * Answer in case of error: - * SimpleResults;NOK;Explanation - * Normal answer: - * SimpleResults;OK;Nb_results;Result_1;…;Result_n - * Nb_results is the number of results in the answer (number of mobiles). - * Result_i follows this format: - * Mobile_MAC;X;Y;Z;Area_name - * Area_name is the name of the area or room in which the mobile is (may - * be empty). + * This is the main source file of OwlPS UDP-to-HTTP, a program that + * allows a client to retrieve results from OwlPS Positioner through + * HTTP. */