Statistics
| Branch: | Revision:

grapes / include / cloud_helper.h @ b9e7dd7b

History | View | Annotate | Download (5.2 KB)

1
/*
2
 *  Copyright (c) 2010 Andrea Zito
3
 *
4
 *  This is free software; see lgpl-2.1.txt
5
 */
6

    
7
#ifndef CLOUD_HELPER_H
8
#define CLOUD_HELPER_H
9

    
10
#define CLOUD_HELPER_MAX_INSTANCES 10
11

    
12
#include <stdint.h>
13
#include <sys/time.h>
14

    
15
#include "net_helper.h"
16

    
17
/**
18
 * @file cloud_helper.h
19
 *
20
 * @brief Cloud communication facility interface.
21
 *
22
 * A clean interface throught which all the cloud communication procedure needed by SOM funcions
23
 * are handled.
24
 */
25

    
26
/**
27
 * Implementation dependant internal representation of the cloud clontext
28
 */
29
struct cloud_helper_contex;
30

    
31
/**
32
 * @brief Initialize all needed internal parameters.
33
 * Initialize the parameters for the cloud facilities and create a context
34
 * representing the cloud.
35
 * Only one instance of net_helper is allowed for a specific nodeID.
36
 * @param[in] local NodeID associated with this instance of cloud_helper.
37
 * @param[in] config Cloud specific configuration options.
38
 */
39
struct cloud_helper_context* cloud_helper_init(struct nodeID *local,
40
                                               const char *config);
41

    
42
/**
43
 * @brief Identifies the cloud_helper instance associated to the specified
44
 * nodeID
45
 * Returns the instance of cloud_helper that was initialized with the
46
 * specified nodeID.
47
 */
48
struct cloud_helper_context* get_cloud_helper_for(const struct nodeID *local);
49

    
50
/**
51
 * @brief Get the value for the specified key from the cloud.
52
 * This function send a request to the cloud for the value associated to the
53
 * specified key. Use the wait4cloud to listen for the answer and
54
 * revc_from_cloud to read the response.
55
 * @param[in] context The contex representing the desired cloud_helper
56
 *                    instance.
57
 * @param[in] key Key to retrieve.
58
 * @param[in] header_ptr A pointer to the header which will be added to the
59
 *                       retrieved data. May be NULL
60
 * @param[in] header_size The length of the header.
61
 * @param[in] free_header A positive value result in buffer_ptr being freed
62
 *                        on request completion
63
 * @return 0 if the request was successfully sent, 1 Otherwise
64
 */
65
int get_from_cloud(struct cloud_helper_context *context, const char *key,
66
                   uint8_t *header_ptr, int header_size, int free_header);
67

    
68
/**
69
 * @brief Returns the timestamp associated to the last GET operation.
70
 * Returns the timestamp associated to the last GET operation or NULL.
71
 * @param[in] context The contex representing the desired cloud_helper
72
 *                    instance.
73
 * @return timestamp ot NULL
74
 */
75
time_t timestamp_cloud(struct cloud_helper_context *context);
76

    
77
/**
78
 * @brief Put on the cloud the value for a specified key.
79
 * This function transparently handles the sending routines.
80
 * @param[in] context The contex representing the desired cloud_helper
81
 *                    instance.
82
 * @param[in] key Key to retrieve.
83
 * @param[in] buffer_ptr A pointer to the buffer in which to store the
84
 *                       retrieved data.
85
 * @param[in] buffer_size The size of the data buffer
86
 * @param[in] free_buffer A positive value result in buffer_ptr being freed
87
 *                        on request completion
88
 * @return 0 on success, 1 on failure
89
 */
90
int put_on_cloud(struct cloud_helper_context *context, const char *key,
91
                 uint8_t *buffer_ptr, int buffer_size, int free_buffer);
92

    
93
/**
94
 * @brief Returns the nodeID identifing the cloud for the specified variant.
95
 * This function transparently handles the identification of the cloud
96
 * node. Thanks to the variant parameter is possible to recover
97
 * nodeIDs which differ wrt to nodeid_equal, but are equal wrt to
98
 * is_cloud_node.
99
 * @param[in] context The contex representing the desired cloud_helper
100
 *                    instance.
101
 * @param[in] variant The variant number for this nodeID.
102
 * @return nodeID identifying the cloud.
103
 */
104
struct nodeID* get_cloud_node(struct cloud_helper_context *context,
105
                              uint8_t variant);
106

    
107
/**
108
 * @brief Check if the specified node references the cloud
109
 * This function transparently handles the comparation of cloud nodes.
110
 * @param[in] context The contex representing the desired cloud_helper
111
 *                    instance.
112
 * @param[in] node The supposed cloud node
113
 * @return 1 if cloud node, 0 otherwise
114
 */
115
int is_cloud_node(struct cloud_helper_context *context,
116
                  struct nodeID* node);
117

    
118
/**
119
 * @brief Check for cloud responses.
120
 * Check if the some cloud GET operation has concluded. It sets a timeout to
121
 * return at most after a given time.
122
 * @param[in] context The contex representing the desired cloud_helper
123
 *                    instance.
124
 * @param[in] tout A pointer to a timer to be used to set the waiting timeout.
125
 * @return 1 if the GET operation was succesful, -1 if the GET operation
126
 *         failed (unkwnown key), 0 otherwise.
127
 */
128
int wait4cloud(struct cloud_helper_context *context, struct timeval *tout);
129

    
130

    
131
/**
132
 * @brief Receive data from the cloud.
133
 * This function transparently handles the receving routines.
134
 * @param[out] buffer_ptr A pointer to the buffer in which to store the retrieved data.
135
 * @param[out] buffer_size The size of the data buffer
136
 * @return The number of received bytes or -1 if some error occurred.
137
 */
138
int recv_from_cloud(struct cloud_helper_context *context, uint8_t *buffer_ptr, int buffer_size);
139

    
140
#endif