module yumaworks-ycontrol {

    namespace "http://yumaworks.com/ns/yumaworks-ycontrol";

    prefix "yctl";

    import yuma-ncx { prefix ncx; }
    import yuma-types { prefix yt; }

    organization "YumaWorks, Inc.";

    contact
        "Support <support at yumaworks.com>";

    description 
       "YumaPro control system message definition.";

    revision 2014-11-19 {
        description
          "Support '*' as the service-id to indicate a server
           event message that is intended for the YControl layer
           itself, called ALL_SERVICES.
           Add shutdown-event message for ALL_SERVICES";
    }

    revision 2014-04-08 {
        description
          "Initial version.";
    }

    container ycontrol {
      ncx:abstract;
      ncx:hidden;

      leaf message-id {
        mandatory true;
        type uint32 {
          range "1 .. max";
        }
        description 
          "Message identifier.
           For server-response and subsys-response message types,
           this value is the same as the corresponding request
           message.";
      }

      leaf message-type {
        mandatory true;
        type enumeration {
          enum server-event {
            description
              "Message from server to sub-system.
               No response expected.";
          }
          enum server-request {
            description
              "Request message from server to sub-system.
               A response is expected.";
          }
          enum server-response {
            description
              "Response message from server to sub-system.
               Sent when subsys-req received.
               No response is expected";
          }
          enum subsys-event {
            description
              "Message from sub-system to server.
               No response expected.";
          }
          enum subsys-request {
            description
              "Request message from sub-system to server.
               A response is expected.";
          }
          enum subsys-response {
            description
              "Response message from sub-system to server.
               Sent when server-req received.
               No response is expected";
          }
          enum ycontrol-error {
            description
              "Response message from either sub-system or server.
               Sent when a recoverable YControl or service layer
               error occurs.

               If non-recoverable error, then session is dropped
               and no response is sent. Example error: message
               is for a service-id that does not exist.
               No response is expected";
          }

        }
        description "Message type";
      }

      leaf server-id {
        mandatory true;
        type union {
          type yt:NcxName;
          type string { length 0; }
        }
        description "Server identifier or empty if not known by subsys";
      }

      leaf subsys-id {
        mandatory true;
        type yt:NcxName;
        description "Subsystem identifier";
      }

      leaf service-id {
        mandatory true;
        type union {
          type yt:NcxName;
          type string {
            pattern '\*';
          }
        }
        description
          "Service identifier. The value '*' indicates a
           server-event message to all services. These messages
           are handled by the ycontrol library, not the individual
           service libraries.";
      }

      choice message-payload {
        mandatory true;
        container payload {
          description
            "This <payload> container is augmented with a
             service-specific container from other modules.";
          
          leaf shutdown-event {
            type empty;
            description
             "Message type: server-event;
              Purpose: The server is shutting down. Sent to
              all services (service-id = '*')

              Expected Response Message: none";
          }  // leaf shutdown-event
        }
        leaf ok {
          type empty;
          description 
            "Sent when a request message is processed
             successfully and no data is needed in the
             response.";
        }
        container error {
          leaf error-number {
            mandatory true;
            type uint32;
            description "Internal error number";
          }

          leaf transaction-id {
            type string;
              description
                "Server specific transaction identifier.
                 Sent from subsystem to server in
                 subsys-response.
                 It identifies the transaction in case multiple
                 transactions are in progress at once.";
          }

          leaf error-message {
            type string;
            description
              "Internal error message, if different from
               get_error_string(error-number).";
          }

          leaf error-index {
            type uint32 {
              range "1 .. max";
            }
            description
              "Internal edit index number from <start-transaction>
               message. Set only if an edit-specific error occurred.";
          }

        }

      }  // choice message-payload

    }  // container ycontrol

}