src/app/clusters/messaging-server/messaging-server.h

   1 /**
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *
   5  *    Licensed under the Apache License, Version 2.0 (the "License");
   6  *    you may not use this file except in compliance with the License.
   7  *    You may obtain a copy of the License at
   8  *
   9  *        http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *    Unless required by applicable law or agreed to in writing, software
  12  *    distributed under the License is distributed on an "AS IS" BASIS,
  13  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *    See the License for the specific language governing permissions and
  15  *    limitations under the License.
  16  */
  17
  18 /**
  19  *
  20  *    Copyright (c) 2020 Silicon Labs
  21  *
  22  *    Licensed under the Apache License, Version 2.0 (the "License");
  23  *    you may not use this file except in compliance with the License.
  24  *    You may obtain a copy of the License at
  25  *
  26  *        http://www.apache.org/licenses/LICENSE-2.0
  27  *
  28  *    Unless required by applicable law or agreed to in writing, software
  29  *    distributed under the License is distributed on an "AS IS" BASIS,
  30  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31  *    See the License for the specific language governing permissions and
  32  *    limitations under the License.
  33  */
  34 /***************************************************************************
  35  * @file
  36  * @brief APIs and defines for the Messaging Server
  37  *plugin.
  38  *******************************************************************************
  39  ******************************************************************************/
  40
  41 #pragma once
  42
  43 // ----------------------------------------------------------------------------
  44 // Message Control byte
  45 // ----------------------------------------------------------------------------
  46
  47 #define ZCL_MESSAGING_CLUSTER_TRANSMISSION_MASK (EMBER_BIT(1) | EMBER_BIT(0))
  48 #define ZCL_MESSAGING_CLUSTER_IMPORTANCE_MASK (EMBER_BIT(3) | EMBER_BIT(2))
  49 #define ZCL_MESSAGING_CLUSTER_RESERVED_MASK (EMBER_BIT(6) | EMBER_BIT(5) | EMBER_BIT(4))
  50 #define ZCL_MESSAGING_CLUSTER_CONFIRMATION_MASK EMBER_BIT(7)
  51
  52 #define ZCL_MESSAGING_CLUSTER_START_TIME_NOW 0x00000000UL
  53 #define ZCL_MESSAGING_CLUSTER_END_TIME_NEVER 0xFFFFFFFFUL
  54 #define ZCL_MESSAGING_CLUSTER_DURATION_UNTIL_CHANGED 0xFFFF
  55
  56 /**
  57  * @brief The message and metadata used by the messaging server plugin.
  58  *
  59  * The application can get and set the message used by the plugin by calling
  60  * ::emberAfPluginMessagingServerGetMessage and
  61  * ::emberAfPluginMessagingServerSetMessage.
  62  */
  63 typedef struct
  64 {
  65     /** The unique unsigned 32-bit number identifier for this message. */
  66     uint32_t messageId;
  67     /** The control bitmask for this message. */
  68     uint8_t messageControl;
  69     /** The time at which the message becomes valid. */
  70     uint32_t startTime;
  71     /** The amount of time in minutes after the start time during which the
  72         message is displayed.
  73      */
  74     uint16_t durationInMinutes;
  75     /** The string containing the message to be delivered. */
  76     uint8_t message[EMBER_AF_PLUGIN_MESSAGING_SERVER_MESSAGE_SIZE + 1];
  77     /** Additional control and status information for a given message. **/
  78     uint8_t extendedMessageControl;
  79     /** Internal control state */
  80     uint8_t messageStatusControl;
  81 } EmberAfPluginMessagingServerMessage;
  82
  83 /**
  84  * @brief Gets the message used by the messaging server plugin.
  85  *
  86  * This function is used to get the message and metadata that the plugin
  87  * will send to clients. For "start now" messages that are current or
  88  * scheduled, the duration is adjusted to reflect how many minutes remain for
  89  * the message. Otherwise, the start time and duration of "start now" messages
  90  * reflect the actual start and the original duration.
  91  *
  92  * @param endpoint The relevant endpoint.
  93  * @param message The ::EmberAfPluginMessagingServerMessage structure
  94  * describing the message.
  95  * @return True if the message is valid or false is the message does not exist
  96  * or is expired.
  97  */
  98 bool emberAfPluginMessagingServerGetMessage(chip::EndpointId endpoint, EmberAfPluginMessagingServerMessage * message);
  99
 100 /**
 101  * @brief Sets the message used by the Messaging server plugin.
 102  *
 103  * This function can be used to set the message and metadata that the plugin
 104  * will send to clients. Setting the start time to zero instructs clients to
 105  * start the message now. For "start now" messages, the plugin will
 106  * automatically adjust the duration reported to clients based on the original
 107  * start time of the message.
 108  *
 109  * @param endpoint The relevant endpoint.
 110  * @param message The ::EmberAfPluginMessagingServerMessage structure
 111  * describing the message.  If NULL, the message is removed from the server.
 112  */
 113 void emberAfPluginMessagingServerSetMessage(chip::EndpointId endpoint, const EmberAfPluginMessagingServerMessage * message);
 114
 115 void emAfPluginMessagingServerPrintInfo(chip::EndpointId endpoint);
 116 void emberAfPluginMessagingServerDisplayMessage(EmberNodeId nodeId, uint8_t srcEndpoint, uint8_t dstEndpoint);
 117 void emberAfPluginMessagingServerCancelMessage(EmberNodeId nodeId, uint8_t srcEndpoint, uint8_t dstEndpoint);