resource/csdk/connectivity/common/inc/uqueue.h

   1 /* ****************************************************************
   2  *
   3  * Copyright 2014 Samsung Electronics All Rights Reserved.
   4  *
   5  *
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *      http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  ******************************************************************/
  20
  21 /**
  22  * @file
  23  *
  24  * This file contains the APIs for queue to be implemented.
  25  */
  26
  27 #ifndef U_QUEUE_H_
  28 #define U_QUEUE_H_
  29
  30 #include "cacommon.h"
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #endif /* __cplusplus */
  36
  37 /**
  38  * Queue message format.
  39  */
  40 typedef struct u_queue_message_t
  41 {
  42     /** Pointer to message. */
  43     void *msg;
  44     /** message size. */
  45     uint32_t size;
  46 } u_queue_message_t;
  47
  48 typedef struct u_queue_element_t u_queue_element;
  49
  50 /**
  51  * Queue element format.
  52  */
  53 struct u_queue_element_t
  54 {
  55     /** pointer to queue message. */
  56     u_queue_message_t *message;
  57     /** Pointer to next queue element. */
  58     u_queue_element *next;
  59 };
  60
  61 /**
  62  * Queue structure.
  63  */
  64 typedef struct u_queue_t
  65 {
  66     /** Head of the queue. */
  67     u_queue_element *element;
  68     /** Number of messages in Queue. */
  69     uint32_t count;
  70 } u_queue_t;
  71
  72 /**
  73  * API to creates queue and initializes the elements.
  74  * @return  u_queue_t pointer if Success, NULL otherwise.
  75  */
  76 u_queue_t *u_queue_create();
  77
  78 /**
  79  * Resets and deletes the queue.
  80  * @param queue- queue pointer.
  81  * @return ::CA_STATUS_OK if Success, ::CA_STATUS_FAILED otherwise.
  82  */
  83 CAResult_t u_queue_delete(u_queue_t *queue);
  84
  85 /**
  86  * Adds message at the end of the queue.
  87  * @param queue pointer to queue.
  88  * @param message Pointer to message.
  89  * @return ::CA_STATUS_OK if Success, ::CA_STATUS_FAILED otherwise.
  90  */
  91 CAResult_t u_queue_add_element(u_queue_t *queue, u_queue_message_t *message);
  92
  93 /**
  94  * Returns the first message in the queue and removes queue element.
  95  * Head is moved to next element.
  96  * @param queue pointer to queue.
  97  * @return pointer to Message if Success, NULL otherwise.
  98  */
  99 u_queue_message_t *u_queue_get_element(u_queue_t *queue);
 100
 101 /**
 102  * Removes head element of the queue.
 103  * @param queue pointer to queue.
 104  * @return ::CA_STATUS_OK if Success, ::CA_STATUS_FAILED otherwise.
 105  */
 106 CAResult_t u_queue_remove_element(u_queue_t *queue);
 107
 108 /**
 109  * @param queue pointer to queue.
 110  * @return number of elements in queue.
 111  */
 112 uint32_t u_queue_get_size(u_queue_t *queue);
 113
 114 /**
 115  * Removes all the messages from Queue and reset message count.
 116  * @param queue pointer to queue.
 117  * @return ::CA_STATUS_OK if Success, ::CA_STATUS_FAILED otherwise.
 118  */
 119 CAResult_t u_queue_reset(u_queue_t *queue);
 120
 121 /**
 122  * Returns the first message in queue, but not remove the element.
 123  * @param queue pointer to queue.
 124  * @return pointer to Message if Success, NULL otherwise.
 125  */
 126 u_queue_message_t *u_queue_get_head(u_queue_t *queue);
 127
 128 /** Data destroy function. **/
 129 typedef void (*QueueDataDestroyFunction)(void *data, uint32_t size);
 130 typedef bool (*QueueContextDataDestroy)(void *data, uint32_t size, void *ctx);
 131
 132 /**
 133  * Removes messages from anywhere in the queue
 134  * @param queue     pointer to queue
 135  * @param callback  Function returns true if element is to be destroyed
 136  * @param ctx       data that should be passed to callback
 137  * @param destroy   Function to destroy the data, if NULL OICFree will be used
 138  * @return ::CA_STATUS_OK if Success, ::CA_STATUS_FAILED otherwise
 139  */
 140 CAResult_t u_queue_remove_req_elements(u_queue_t *queue,
 141                                        QueueContextDataDestroy callback, void *ctx,
 142                                        QueueDataDestroyFunction destroy);
 143
 144 #ifdef __cplusplus
 145 } /* extern "C" */
 146 #endif /* __cplusplus */
 147
 148 #endif /* U_QUEUE_H_ */