Statistics
| Branch: | Revision:

grapes / include / cloud_helper.h @ master

History | View | Annotate | Download (6.73 KB)

1 dd3024b0 Andrea Zito
/*
2
 *  Copyright (c) 2010 Andrea Zito
3
 *
4
 *  This is free software; see lgpl-2.1.txt
5
 */
6
7 5033613a Andrea Zito
#ifndef CLOUD_HELPER_H
8
#define CLOUD_HELPER_H
9
10
#include <stdint.h>
11
#include <sys/time.h>
12
13
#include "net_helper.h"
14
15
/**
16
 * @file cloud_helper.h
17
 *
18
 * @brief Cloud communication facility interface.
19
 *
20
 * A clean interface throught which all the cloud communication procedure needed by SOM funcions
21
 * are handled.
22 78dc8c0c Andrea Zito
 *
23
 * If thread are used, the caller must ensured that calls to cloud_helper_init
24
 * and get_cloud_helper_for are synchronized.
25 5033613a Andrea Zito
 */
26
27
/**
28
 * Implementation dependant internal representation of the cloud clontext
29
 */
30
struct cloud_helper_contex;
31
32
/**
33
 * @brief Initialize all needed internal parameters.
34 b9e7dd7b Andrea Zito
 * Initialize the parameters for the cloud facilities and create a context
35 78dc8c0c Andrea Zito
 * representing the cloud. Only one instance of net_helper is allowed for a
36
 * specific nodeID.
37
 *
38 5033613a Andrea Zito
 * @param[in] local NodeID associated with this instance of cloud_helper.
39
 * @param[in] config Cloud specific configuration options.
40
 */
41 b9e7dd7b Andrea Zito
struct cloud_helper_context* cloud_helper_init(struct nodeID *local,
42
                                               const char *config);
43 5033613a Andrea Zito
44
/**
45 b9e7dd7b Andrea Zito
 * @brief Identifies the cloud_helper instance associated to the specified
46
 * nodeID
47
 * Returns the instance of cloud_helper that was initialized with the
48
 * specified nodeID.
49 5033613a Andrea Zito
 */
50 b9e7dd7b Andrea Zito
struct cloud_helper_context* get_cloud_helper_for(const struct nodeID *local);
51 5033613a Andrea Zito
52
/**
53
 * @brief Get the value for the specified key from the cloud.
54 b9e7dd7b Andrea Zito
 * This function send a request to the cloud for the value associated to the
55
 * specified key. Use the wait4cloud to listen for the answer and
56
 * revc_from_cloud to read the response.
57
 * @param[in] context The contex representing the desired cloud_helper
58
 *                    instance.
59 5033613a Andrea Zito
 * @param[in] key Key to retrieve.
60 b9e7dd7b Andrea Zito
 * @param[in] header_ptr A pointer to the header which will be added to the
61
 *                       retrieved data. May be NULL
62 89b16ba8 Andrea Zito
 * @param[in] header_size The length of the header.
63 b9e7dd7b Andrea Zito
 * @param[in] free_header A positive value result in buffer_ptr being freed
64
 *                        on request completion
65 dd3024b0 Andrea Zito
 * @return 0 if the request was successfully sent, 1 Otherwise
66 5033613a Andrea Zito
 */
67 b9e7dd7b Andrea Zito
int get_from_cloud(struct cloud_helper_context *context, const char *key,
68
                   uint8_t *header_ptr, int header_size, int free_header);
69 5033613a Andrea Zito
70
/**
71 98b047dd Andrea Zito
 * @brief Get the value for key or return default value
72
 * This function send a request to the cloud for the value associated to the
73
 * specified key. Use the wait4cloud to listen for the answer and
74
 * revc_from_cloud to read the response.
75
 *
76
 * If the specified key isn't present on the cloud, return the default value
77
 * @param[in] context The contex representing the desired cloud_helper
78
 *                    instance.
79
 * @param[in] key Key to retrieve.
80
 * @param[in] header_ptr A pointer to the header which will be added to the
81
 *                       retrieved data. May be NULL
82
 * @param[in] header_size The length of the header.
83
 * @param[in] free_header A positive value result in buffer_ptr being freed
84
 *                        on request completion
85
 * @param[in] defval_ptr A pointer to the default value to use if key is missing
86
 * @param[in] defval_size The length of the default value
87
 * @param[in] free_defvar A positive value result in defval_ptr being freed on
88
                          request comletion
89
 * @return 0 if the request was successfully sent, 1 Otherwise
90
 */
91
int get_from_cloud_default(struct cloud_helper_context *context, const char *key,
92
                           uint8_t *header_ptr, int header_size, int free_header,
93
                           uint8_t *defval_ptr, int defval_size, int free_defval);
94
95
/**
96 0e9bde83 Andrea Zito
 * @brief Returns the timestamp associated to the last GET operation.
97
 * Returns the timestamp associated to the last GET operation or NULL.
98 b9e7dd7b Andrea Zito
 * @param[in] context The contex representing the desired cloud_helper
99
 *                    instance.
100 0e9bde83 Andrea Zito
 * @return timestamp ot NULL
101
 */
102
time_t timestamp_cloud(struct cloud_helper_context *context);
103
104
/**
105 5033613a Andrea Zito
 * @brief Put on the cloud the value for a specified key.
106
 * This function transparently handles the sending routines.
107 b9e7dd7b Andrea Zito
 * @param[in] context The contex representing the desired cloud_helper
108
 *                    instance.
109 5033613a Andrea Zito
 * @param[in] key Key to retrieve.
110 b9e7dd7b Andrea Zito
 * @param[in] buffer_ptr A pointer to the buffer in which to store the
111
 *                       retrieved data.
112 49b99aeb Andrea Zito
 * @param[in] buffer_size The size of the data buffer
113 b9e7dd7b Andrea Zito
 * @param[in] free_buffer A positive value result in buffer_ptr being freed
114
 *                        on request completion
115 5033613a Andrea Zito
 * @return 0 on success, 1 on failure
116
 */
117 b9e7dd7b Andrea Zito
int put_on_cloud(struct cloud_helper_context *context, const char *key,
118
                 uint8_t *buffer_ptr, int buffer_size, int free_buffer);
119 5033613a Andrea Zito
120
/**
121 0e9bde83 Andrea Zito
 * @brief Returns the nodeID identifing the cloud for the specified variant.
122
 * This function transparently handles the identification of the cloud
123
 * node. Thanks to the variant parameter is possible to recover
124 b9e7dd7b Andrea Zito
 * nodeIDs which differ wrt to nodeid_equal, but are equal wrt to
125
 * is_cloud_node.
126
 * @param[in] context The contex representing the desired cloud_helper
127
 *                    instance.
128 0e9bde83 Andrea Zito
 * @param[in] variant The variant number for this nodeID.
129 5033613a Andrea Zito
 * @return nodeID identifying the cloud.
130
 */
131 b9e7dd7b Andrea Zito
struct nodeID* get_cloud_node(struct cloud_helper_context *context,
132
                              uint8_t variant);
133 5033613a Andrea Zito
134
/**
135 ef8002fd Andrea Zito
 * @brief Check if the specified node references the cloud
136
 * This function transparently handles the comparation of cloud nodes.
137 b9e7dd7b Andrea Zito
 * @param[in] context The contex representing the desired cloud_helper
138
 *                    instance.
139 ef8002fd Andrea Zito
 * @param[in] node The supposed cloud node
140
 * @return 1 if cloud node, 0 otherwise
141
 */
142 b9e7dd7b Andrea Zito
int is_cloud_node(struct cloud_helper_context *context,
143
                  struct nodeID* node);
144 ef8002fd Andrea Zito
145
/**
146 5033613a Andrea Zito
 * @brief Check for cloud responses.
147 b9e7dd7b Andrea Zito
 * Check if the some cloud GET operation has concluded. It sets a timeout to
148
 * return at most after a given time.
149
 * @param[in] context The contex representing the desired cloud_helper
150
 *                    instance.
151 5033613a Andrea Zito
 * @param[in] tout A pointer to a timer to be used to set the waiting timeout.
152 b9e7dd7b Andrea Zito
 * @return 1 if the GET operation was succesful, -1 if the GET operation
153
 *         failed (unkwnown key), 0 otherwise.
154 5033613a Andrea Zito
 */
155
int wait4cloud(struct cloud_helper_context *context, struct timeval *tout);
156
157
158
/**
159
 * @brief Receive data from the cloud.
160
 * This function transparently handles the receving routines.
161 849c120e Andrea Zito
 * If the read bytes number is less than the buffer size or equal 0 than the
162
 * current response has been completely read.
163 5033613a Andrea Zito
 * @param[out] buffer_ptr A pointer to the buffer in which to store the retrieved data.
164
 * @param[out] buffer_size The size of the data buffer
165
 * @return The number of received bytes or -1 if some error occurred.
166
 */
167
int recv_from_cloud(struct cloud_helper_context *context, uint8_t *buffer_ptr, int buffer_size);
168
169
#endif