module yumaworks-ycontrol {

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

    prefix "yctl";

    import ietf-yang-structure-ext { prefix sx; }
    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.

     Copyright (c) 2014 - 2023 YumaWorks, Inc. All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject
     to the license terms contained in, the BSD 3-Clause License
     http://opensource.org/licenses/BSD-3-Clause";

    revision 2023-08-04 {
      description
        "22.10T-11: Change CLI container to sx:structure";
    }

    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.";
    }

    sx:structure 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

}
