Statistics
| Branch: | Revision:

grapes / include / cloud_helper.h @ 0e9bde83

History | View | Annotate | Download (4.49 KB)

1
#ifndef CLOUD_HELPER_H
2
#define CLOUD_HELPER_H
3

    
4
#define CLOUD_HELPER_MAX_INSTANCES 10
5

    
6
#include <stdint.h>
7
#include <sys/time.h>
8

    
9
#include "net_helper.h"
10

    
11
/**
12
 * @file cloud_helper.h
13
 *
14
 * @brief Cloud communication facility interface.
15
 *
16
 * A clean interface throught which all the cloud communication procedure needed by SOM funcions
17
 * are handled.
18
 */
19

    
20
/**
21
 * Implementation dependant internal representation of the cloud clontext
22
 */
23
struct cloud_helper_contex;
24

    
25
/**
26
 * @brief Initialize all needed internal parameters.
27
 * Initialize the parameters for the cloud facilities and create a context representing the cloud.
28
 * Only one instance of net_helper is allowed for a specific nodeID.
29
 * @param[in] local NodeID associated with this instance of cloud_helper.
30
 * @param[in] config Cloud specific configuration options.
31
 */
32
struct cloud_helper_context* cloud_helper_init(struct nodeID *local, const char *config);
33

    
34
/**
35
 * @brief Identifies the cloud_helper instance associated to the specified nodeID
36
 * Returns the instance of cloud_helper that was initialized with the specified nodeID.
37
 */
38
struct cloud_helper_context* get_cloud_helper_for(struct nodeID *local);
39

    
40
/**
41
 * @brief Get the value for the specified key from the cloud.
42
 * This function send a request to the cloud for the value associated to the specified key.
43
 * Use the wait4cloud to listen for the answer and revc_from_cloud to read the response.
44
 * @param[in] context The contex representing the desired cloud_helper instance.
45
 * @param[in] key Key to retrieve.
46
 * @param[in] header_ptr A pointer to the header which will be added to the retrieved data. May be NULL
47
 * @param[in] header_size The length of the header.
48
 * @return 0 if the request was successfully sent, 1 0therwise
49
 */
50
int get_from_cloud(struct cloud_helper_context *context, char *key, uint8_t *header_ptr, int header_size);
51

    
52
/**
53
 * @brief Returns the timestamp associated to the last GET operation.
54
 * Returns the timestamp associated to the last GET operation or NULL.
55
 * @param[in] context The contex representing the desired cloud_helper instance.
56
 * @return timestamp ot NULL
57
 */
58
time_t timestamp_cloud(struct cloud_helper_context *context);
59

    
60
/**
61
 * @brief Put on the cloud the value for a specified key.
62
 * This function transparently handles the sending routines.
63
 * @param[in] context The contex representing the desired cloud_helper instance.
64
 * @param[in] key Key to retrieve.
65
 * @param[in] buffer_ptr A pointer to the buffer in which to store the retrieved data.
66
 * @param[in] buffer_size The size of the data buffer 
67
 * @return 0 on success, 1 on failure
68
 */
69
int put_on_cloud(struct cloud_helper_context *context, char *key, uint8_t *buffer_ptr, int buffer_size);
70

    
71
/**
72
 * @brief Returns the nodeID identifing the cloud for the specified variant.
73
 * This function transparently handles the identification of the cloud
74
 * node. Thanks to the variant parameter is possible to recover
75
 * nodeIDs which differ wrt to nodeid_equal, but are equal wrt to is_cloud_node.
76
 * @param[in] context The contex representing the desired cloud_helper instance.
77
 * @param[in] variant The variant number for this nodeID.
78
 * @return nodeID identifying the cloud.
79
 */
80
struct nodeID* get_cloud_node(struct cloud_helper_context *context, uint8_t variant);
81

    
82
/**
83
 * @brief Check if the specified node references the cloud
84
 * This function transparently handles the comparation of cloud nodes.
85
 * @param[in] context The contex representing the desired cloud_helper instance.
86
 * @param[in] node The supposed cloud node
87
 * @return 1 if cloud node, 0 otherwise
88
 */
89
int is_cloud_node(struct cloud_helper_context *context, struct nodeID* node);
90

    
91
/**
92
 * @brief Check for cloud responses.
93
 * Check if the some cloud GET operation has concluded. It sets a timeout to return at most after a given time.
94
 * @param[in] context The contex representing the desired cloud_helper instance.
95
 * @param[in] tout A pointer to a timer to be used to set the waiting timeout.
96
 * @return 1 if the GET operation was succesful, -1 if the GET operation failed (unkwnown key), 0 otherwise.
97
 */
98
int wait4cloud(struct cloud_helper_context *context, struct timeval *tout);
99

    
100

    
101
/**
102
 * @brief Receive data from the cloud.
103
 * This function transparently handles the receving routines.
104
 * @param[out] buffer_ptr A pointer to the buffer in which to store the retrieved data.
105
 * @param[out] buffer_size The size of the data buffer
106
 * @return The number of received bytes or -1 if some error occurred.
107
 */
108
int recv_from_cloud(struct cloud_helper_context *context, uint8_t *buffer_ptr, int buffer_size);
109

    
110
#endif