Revision b9e7dd7b include/cloud_helper.h

View differences:

include/cloud_helper.h
30 30

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

  
40 42
/**
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
 * @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.
43 47
 */
44
struct cloud_helper_context* get_cloud_helper_for(struct nodeID *local);
48
struct cloud_helper_context* get_cloud_helper_for(const struct nodeID *local);
45 49

  
46 50
/**
47 51
 * @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.
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.
51 57
 * @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
58
 * @param[in] header_ptr A pointer to the header which will be added to the
59
 *                       retrieved data. May be NULL
53 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
54 63
 * @return 0 if the request was successfully sent, 1 Otherwise
55 64
 */
56
int get_from_cloud(struct cloud_helper_context *context, char *key, uint8_t *header_ptr, int header_size);
65
int get_from_cloud(struct cloud_helper_context *context, const char *key,
66
                   uint8_t *header_ptr, int header_size, int free_header);
57 67

  
58 68
/**
59 69
 * @brief Returns the timestamp associated to the last GET operation.
60 70
 * Returns the timestamp associated to the last GET operation or NULL.
61
 * @param[in] context The contex representing the desired cloud_helper instance.
71
 * @param[in] context The contex representing the desired cloud_helper
72
 *                    instance.
62 73
 * @return timestamp ot NULL
63 74
 */
64 75
time_t timestamp_cloud(struct cloud_helper_context *context);
......
66 77
/**
67 78
 * @brief Put on the cloud the value for a specified key.
68 79
 * This function transparently handles the sending routines.
69
 * @param[in] context The contex representing the desired cloud_helper instance.
80
 * @param[in] context The contex representing the desired cloud_helper
81
 *                    instance.
70 82
 * @param[in] key Key to retrieve.
71
 * @param[in] buffer_ptr A pointer to the buffer in which to store the retrieved data.
83
 * @param[in] buffer_ptr A pointer to the buffer in which to store the
84
 *                       retrieved data.
72 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
73 88
 * @return 0 on success, 1 on failure
74 89
 */
75
int put_on_cloud(struct cloud_helper_context *context, char *key, uint8_t *buffer_ptr, int buffer_size);
90
int put_on_cloud(struct cloud_helper_context *context, const char *key,
91
                 uint8_t *buffer_ptr, int buffer_size, int free_buffer);
76 92

  
77 93
/**
78 94
 * @brief Returns the nodeID identifing the cloud for the specified variant.
79 95
 * This function transparently handles the identification of the cloud
80 96
 * 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.
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.
83 101
 * @param[in] variant The variant number for this nodeID.
84 102
 * @return nodeID identifying the cloud.
85 103
 */
86
struct nodeID* get_cloud_node(struct cloud_helper_context *context, uint8_t variant);
104
struct nodeID* get_cloud_node(struct cloud_helper_context *context,
105
                              uint8_t variant);
87 106

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

  
97 118
/**
98 119
 * @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.
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.
101 124
 * @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.
125
 * @return 1 if the GET operation was succesful, -1 if the GET operation
126
 *         failed (unkwnown key), 0 otherwise.
103 127
 */
104 128
int wait4cloud(struct cloud_helper_context *context, struct timeval *tout);
105 129

  

Also available in: Unified diff