include/event/data_accessor.h

   1 /*
   2  * sync-agent
   3  * Copyright (c) 2012 Samsung Electronics Co., Ltd.
   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 #ifndef DATA_ACCESSOR_H_
  19 #define DATA_ACCESSOR_H_
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif                          /* __cplusplus */
  24
  25 /**
  26  * @file        data_accessor.h
  27  * @brief       Support to access (create, append, get, remove) event packet structure
  28  */
  29
  30 /** @addtogroup event
  31  *      @{
  32  */
  33
  34 /**
  35  * Structure of Event Packet
  36  */
  37         typedef struct {
  38                 int event_num;
  39                        /**< event number described in event config file */
  40                 char *size;
  41                         /**< need to iterate real data */
  42                 char *data;
  43                         /**< real data expected to send */
  44         } sync_agent_event_data_s;
  45
  46 /**
  47  * Type of parameter in sync_agent_event_data_s
  48  */
  49         typedef enum {
  50                 SYNC_AGENT_EVENT_PARAM_TYPE_INTEGER = 'I',
  51                                                    /**< Interger type */
  52                 SYNC_AGENT_EVENT_PARAM_TYPE_STRING = 'S'
  53                                                  /**< String type */
  54         } sync_agent_event_param_type_e;
  55
  56 /**
  57  * API to add parameter to Event packet
  58  * @remarks Once one parameter is added each time it's invoked. Parameter type can be Number or String
  59  *
  60  * @par Usage:
  61  * @code
  62                 int event_num = 1;
  63                 int event_int_data = 0;
  64                 char *event_char_data = NULL;
  65                 sync_agent_event_data_s *request_event = NULL;
  66                 ...
  67                 request_event = sync_agent_create_event(event_num);
  68                 if (request_event == NULL) {
  69                         // error handling
  70                         ...
  71                 }
  72
  73                 sync_agent_append_event_data_param(request_event, SYNC_AGENT_EVENT_PARAM_TYPE_INTEGER, &event_int_data);
  74                 sync_agent_append_event_data_param(request_event, SYNC_AGENT_EVENT_PARAM_TYPE_STRING, event_char_data);
  75                 ...
  76  *
  77  * @endcode
  78  *
  79  * @param[in] iter sync_agent_event_data_s pointer parameters to be added
  80  * @param[in] type parameter type (SYNC_AGENT_EVENT_PARAM_TYPE_INTEGER, SYNC_AGENT_EVENT_PARAM_TYPE_STRING) @ref sync_agent_event_param_type_e
  81  * @param[in] data real parameter data
  82  *
  83  * @par Since:
  84  *
  85  *
  86  * @see sync_agent_create_noti(int)
  87  *
  88  */
  89         void sync_agent_append_event_data_param(sync_agent_event_data_s * iter, sync_agent_event_param_type_e type, void *data);
  90
  91 /**
  92  * API to extract parameter from Event packet
  93  * @remarks This function will be used when extracting received event packet.
  94  * extracted order is matched the order of @ref sync_agent_append_event_data_param().
  95  *
  96  * @par Usage:
  97  * @code
  98                 int event_num = 1;
  99                 int event_int_data = 0;
 100                 int result_int = 0;
 101                 char *result_char = NULL;
 102                 sync_agent_event_error_e error = SYNC_AGENT_EVENT_SUCCESS;
 103                 sync_agent_event_data_s *request_event = NULL;
 104                 sync_agent_event_data_s *response_event = NULL;
 105                 ...
 106                 request_event = sync_agent_create_event(event_num);
 107                 if (request_event == NULL) {
 108                         // error handling
 109                         ...
 110                 }
 111
 112                 sync_agent_append_event_data_param(request_event, SYNC_AGENT_EVENT_PARAM_TYPE_INTEGER, &event_int_data);
 113                 ...
 114                 response_event = sync_agent_send_event(request_event, &error);
 115                 if (error != SYNC_AGENT_EVENT_SUCCESS) {
 116                         // error handling
 117                         ...
 118                 }
 119
 120                 if (response_event == NULL) {
 121                         // error handling
 122                         ...
 123                 }
 124
 125                 sync_agent_get_event_data_param(response_event, &result_int);
 126                 sync_agent_get_event_data_param(response_event, &result_char);
 127                 ...
 128  *
 129  * @endcode
 130  *
 131  * @param[in] iter sync_agent_event_data_s pointer parameters to be extracted
 132  * @param[in] data as returned by sync_agent_get_event_data_param() - real extracted data
 133  *
 134  * @par Since
 135  *
 136  *
 137  * @see _event_listener(void *)
 138  *
 139  */
 140         void sync_agent_get_event_data_param(sync_agent_event_data_s * iter, void *data);
 141
 142 /**
 143  * API to free sync_agent_event_data_s pointer (event object)
 144  *
 145  * @par Usage:
 146  * @code
 147                 int event_num = 1;
 148                 sync_agent_event_data_s *request_event = NULL;
 149                 ...
 150                 request_event = sync_agent_create_event(event_num);
 151                 if (request_event == NULL) {
 152                         // error handling
 153                         ...
 154                 }
 155                 ...
 156                 sync_agent_free_event_data(request_event);
 157                 ...
 158  *
 159  * @endcode
 160  *
 161  * @param[in] event     event object
 162  *
 163  * @par Since:
 164  *
 165  *
 166  * @see sync_agent_free_noti(sync_agent_event_data_s *)
 167  *
 168  */
 169         void sync_agent_free_event_data(sync_agent_event_data_s * event);
 170
 171 /**
 172  *      @}
 173  */
 174
 175 #ifdef __cplusplus
 176 }
 177 #endif                          /* __cplusplus */
 178 #endif                          /* EVENT_DATA_ACCESSOR_H_ */