Dynamic realm registration

[anna.git] / include / anna / diameter.comm / Engine.hpp

diff --git a/include/anna/diameter.comm/Engine.hpp b/include/anna/diameter.comm/Engine.hpp
index d1c276e..8ec2757 100644 (file)
--- a/include/anna/diameter.comm/Engine.hpp
+++ b/include/anna/diameter.comm/Engine.hpp
@@ -94,6 +94,27 @@ class LocalServer;
 class Engine : public anna::app::Component {
 public:
 
+  /**
+   * Sets the base protocol codec engine used internally
+   *
+   * @param baseProtocolCodecEngine This will be used internally during invokation of @readCEA, @readDPA and @readDWA on servers,
+   * and also used during base protocol messages tracing (if debug traces are enabled). You could provide NULL but you must be
+   * sure that neither of the former situations are going to happen or an exception will be thrown. It is recommended to register
+   * a codec engine pointed to a base protocol stack (you can use the files 'avps_ietf.xml' and 'commands_baseProtocol.xml'
+   * located on ANNA suite project under 'source/diameter/stack/setups', or perhaps you can create your own dictionary from
+   * file or directly with the dictionay creation API. Even you can use a greater dictionary (application dictionary), the
+   * only condition is that must contain the resources to build base protocol messages. You could provide this in engine constructor,
+   * but don't forget it.
+  */
+  void setBaseProtocolCodecEngine(codec::Engine *baseProtocolCodecEngine) throw() { a_baseProtocolCodecEngine = baseProtocolCodecEngine; }
+
+  /**
+   * Gets the base protocol codec engine used internally
+   *
+   * @see setBaseProtocolCodecEngine
+   */
+  codec::Engine * getBaseProtocolCodecEngine() const throw() { return a_baseProtocolCodecEngine; }
+
   /**
      Diameter application node realm name (used to be the site domain name).
 
@@ -185,8 +206,16 @@ public:
    * @param cer Capabilities-Exchange-Request message (encoded) for the client-sessions bind.
    * @param dwr Device-Watchdog-Request message (encoded) for the client-sessions keep-alive.
    */
-  void setCERandDWR(const anna::DataBlock & cer, const anna::DataBlock & dwr) throw(anna::RuntimeException);
+  void setClientCERandDWR(const anna::DataBlock & cer, const anna::DataBlock & dwr) throw(anna::RuntimeException);
 
+  /**
+   * Sets CER and DWR diameter messages to be used over created client-sessions. If empty string is provided for CER and/or DWR, default version will be configured.
+   * Its recommended to set this global configuration although it is possible to configure each client-session separately.
+   *
+   * @param cer Capabilities-Exchange-Request xml message path file for the client-sessions bind. If empty string is provided (default), a default version for CER will be encoded.
+   * @param dwr Device-Watchdog-Request xml message path file for the client-sessions keep-alive. If empty string is provided (default), a default version for DWR will be encoded.
+   */
+  void setClientCERandDWR(const std::string & cer = "", const std::string & dwr = "") throw(anna::RuntimeException);
 
   /**
    * Sets the watchdog period (DWR) for client-sessions.
@@ -610,12 +639,30 @@ public:
   void resetStatistics() throw();
 
 
+  /**
+   * Engine lazy initialization. Used if the engine is created when application is already running; for example
+   * on dynamic realms registration. At the moment is not actually needed (nothing is done at initialization),
+   * but it is recommended to start the component and set its state as 'running' from the point of view of the
+   * application.
+   */
+  void lazyInitialize() throw(RuntimeException);
+
+
 protected:
   /**
      Constructor.
+
      @param className Component class name
+     @param baseProtocolCodecEngine This will be used internally during invokation of @readCEA, @readDPA and @readDWA on servers,
+     and also used during base protocol messages tracing (if debug traces are enabled). You could provide NULL but you must be
+     sure that neither of the former situations are going to happen or an exception will be thrown. It is recommended to register
+     a codec engine pointed to a base protocol stack (you can use the files 'avps_ietf.xml' and 'commands_baseProtocol.xml'
+     located on ANNA suite project under 'source/diameter/stack/setups', or perhaps you can create your own dictionary from
+     file or directly with the dictionay creation API. Even you can use a greater dictionary (application dictionary), the
+     only condition is that must contain the resources to build base protocol messages. You could use @setBaseProtocolCodecEngine
+     to set this reference later; don't forget it.
   */
-  Engine(const char *className);
+  Engine(const char *className, codec::Engine *baseProtocolCodecEngine);
 
 
   // INTERNAL CREATORS AND CLOSE METHODS
@@ -668,6 +715,9 @@ protected:
 
 private:
 
+  // Internal use: tracing and readCEA/DPA/DWA
+  codec::Engine *a_baseProtocolCodecEngine;
+
   std::string a_realm;
   std::string a_host;
   bool a_autoBind;
@@ -701,7 +751,7 @@ private:
   void eraseDeprecatedIdleEntities() throw();
 
   // Component:
-  void do_initialize() throw() {;}
+  void do_initialize() throw(anna::RuntimeException);
   void do_stop() throw();
 
   // Integrity: