src/README.md

   1 #==================================================================================\r
   2 \r
   3 #        Copyright (c) 2018-2019 SAMSUNG and AT&T Intellectual Property.\r
   4 #\r
   5 #   Licensed under the Apache License, Version 2.0 (the "License");\r
   6 #   you may not use this file except in compliance with the License.\r
   7 #   You may obtain a copy of the License at\r
   8 #\r
   9 #       http://www.apache.org/licenses/LICENSE-2.0\r
  10 #\r
  11 #   Unless required by applicable law or agreed to in writing, software\r
  12 #   distributed under the License is distributed on an "AS IS" BASIS,\r
  13 #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  14 #   See the License for the specific language governing permissions and\r
  15 #   limitations under the License.\r
  16 #==================================================================================\r
  17 \r
  18 \r
  19 This document gives an overview of the base class of a simple xAPP class. It is used to build the kpi-xapp executable\r
  20 \r
  21 Pre-requisitis : nanomsg libraries, nng libraries, hiredis libraries and ric messaging library + header must be installed and visible on standard library/include paths (via LD_LIBRARY_PATH, LIBRARY_PATH, CPATH)\r
  22 \r
  23 Usage Guidelines :\r
  24 The base XaPP class is defined in xapp_utils.hpp.  An XaPP class object  can be instantiated in a number of ways :\r
  25 \r
  26 1. XaPP(char *app_name, char *protocol, int redis_port, int message_size) : where \r
  27         - app_name points to a char array to identify this xapp (e.g "my_app_1") \r
  28         - protocol points to a char array to specify the protocol/port on  which this xAPP listens for messages (e.g "tcp:4561")\r
  29     - redis_port is the port to interact with Redis DB\r
  30         - message_size is the maximum size of messages allowed to send ..\r
  31 \r
  32         In this invocation, the number of listener threads (invoked when XaPP.Start() is called) is determined automatically based on hardware\r
  33 \r
  34 \r
  35 2. XaPP(char *app_name, char *protocol, int redis_port, int message_size, int num_threads) : (RECOMMENDED)    where \r
  36         - app_name points to a char array to identify this xapp (e.g "my_app_1") \r
  37         - protocol points to a char array to specify the protocol/port on  which this xAPP listens for messages (e.g "tcp:4561")\r
  38     - redis_port is the port to interact with Redis DB\r
  39         - message_size is the maximum size of messages allowed to send ..\r
  40         - num_threads is the number of threads to invoke on which the XaPP listens for and processes messages\r
  41 \r
  42 \r
  43 3. The XaPP object can start listening to messages using the Start function, with two variants :\r
  44 \r
  45         - XaPP.Start(message_handler) : in this invocation, any message received by the XaPP is passed on the message_handler function which must have the signature bool *(rmr_mbuf_t *).  \r
  46         If the message handler wishes to respond, it must modify the message buffer in place and respond with a true value, else respond with false.\r
  47 \r
  48         - XaPP.Start(message_handler, error_handler) : in this invocation, the user can specify an error_handler function, which must have the signature void *(rmr_mubf_t *) if the sending of a message (processed by message_handler) fails. \r
  49 \r
  50 \r
  51 4. The XaPP object can be used to send messages using the Send function with two variants :\r
  52         - XaPP.Send(int message_type, int message_length, void *message_payload)\r
  53         - XaPP.Send(rmr_mbuf_t * message);\r
  54         They return true if message was sent successfuly and false if not\r
  55 \r
  56 \r
  57 If the XaPP is started with multiple listening threads, they all share the same RMR context and invoke the same message handler/error handler user functions. Hence these are expected to be thread safe. Since all threads will listen to RMR, there is no guarantee  which thread receives which message.\r
  58 \r
  59 \r
  60 ASN1 PDU Processing\r
  61 -------------------\r
  62 \r
  63 1. The basic CuCpResourceStatusReport processing is handled in KPI-Message-Handler which handles the decoding of the message and getting the IEs.\r
  64 \r
  65 \r
  66 Redis DB Store\r
  67 --------------\r
  68 \r
  69 1. The Redis DB store is done using the APIs provided by the hiredis libraries and handled in KPI-Monitoring.\r
  70 \r
  71 \r
  72 --- The kpi-xapp is a basic example to demonstrate RMR and DB store. The kpi-xapp just uses the basic xAPP class but with message processing done by message_processing.cc and store done by kpi_db.cc. \r
  73 \r
  74 It receives CuCpResourceStatusReport message over RMR, decodes it, extracts elements and stores the content in Redis DB.\r