Statistics
| Branch: | Revision:

grapes / include / cloud_helper.h @ dd3024b0

History | View | Annotate | Download (4.58 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 representing the cloud.
34
 * Only one instance of net_helper is allowed for a specific nodeID.
35
 * @param[in] local NodeID associated with this instance of cloud_helper.
36
 * @param[in] config Cloud specific configuration options.
37
 */
38
struct cloud_helper_context* cloud_helper_init(struct nodeID *local, const char *config);
39

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

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

    
58
/**
59
 * @brief Returns the timestamp associated to the last GET operation.
60
 * Returns the timestamp associated to the last GET operation or NULL.
61
 * @param[in] context The contex representing the desired cloud_helper instance.
62
 * @return timestamp ot NULL
63
 */
64
time_t timestamp_cloud(struct cloud_helper_context *context);
65

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

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

    
88
/**
89
 * @brief Check if the specified node references the cloud
90
 * This function transparently handles the comparation of cloud nodes.
91
 * @param[in] context The contex representing the desired cloud_helper instance.
92
 * @param[in] node The supposed cloud node
93
 * @return 1 if cloud node, 0 otherwise
94
 */
95
int is_cloud_node(struct cloud_helper_context *context, struct nodeID* node);
96

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

    
106

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

    
116
#endif