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 |