All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
aerospike_info.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2016 Aerospike, Inc.
3  *
4  * Portions may be licensed to Aerospike, Inc. under one or more contributor
5  * license agreements.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
8  * use this file except in compliance with the License. You may obtain a copy of
9  * the License at http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14  * License for the specific language governing permissions and limitations under
15  * the License.
16  */
17 #pragma once
18 
19 /**
20  * @defgroup info_operations Info Operations
21  * @ingroup client_operations
22  *
23  * The Info API provides the ability to query an Aerospike cluster for
24  * information.
25  *
26  * The following API are provided:
27  * - aerospike_info_host() - Query a single host in the cluster.
28  * - aerospike_info_foreach() - Query every host in the cluster.
29  *
30  */
31 
32 #include <aerospike/aerospike.h>
34 #include <aerospike/as_error.h>
35 #include <aerospike/as_node.h>
36 #include <aerospike/as_policy.h>
37 #include <aerospike/as_status.h>
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 /******************************************************************************
44  * TYPES
45  *****************************************************************************/
46 
47 /**
48  * Callback for aerospike_info_foreach()
49  *
50  * @param err The status and possible error information for the info request.
51  * @param node The node which provided the response.
52  * @param req The initial request.
53  * @param res The response to the info request.
54  * @param udata The udata provided to the aerospike_info_foreach()
55  *
56  * @return TRUE to continue to the next info response. FALSE to stop processing.
57  *
58  * @ingroup info_operations
59  */
60 typedef bool (*aerospike_info_foreach_callback)(const as_error* err, const as_node* node, const char* req, char* res, void* udata);
61 
62 /******************************************************************************
63  * FUNCTIONS
64  *****************************************************************************/
65 
66 /**
67  * Send an info request to a specific server node. The response must be freed by the caller on success.
68  *
69  * ~~~~~~~~~~{.c}
70  * char* res = NULL;
71  * if ( aerospike_info_host(&as, &err, NULL, node, "info", &res) != AEROSPIKE_OK ) {
72  * // handle error
73  * }
74  * else {
75  * // handle response
76  * free(res);
77  * }
78  * ~~~~~~~~~~
79  *
80  * @param as The aerospike instance to use for this operation.
81  * @param err The as_error to be populated if an error occurs.
82  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
83  * @param node The server node to send the request to.
84  * @param req The info request to send.
85  * @param res The response from the node. The response will be a NULL terminated string,
86  * allocated by the function, and must be freed by the caller.
87  *
88  * @return AEROSPIKE_OK on success. Otherwise an error.
89  *
90  * @ingroup info_operations
91  */
94  aerospike* as, as_error* err, const as_policy_info* policy, as_node* node,
95  const char* req, char** res
96  );
97 
98 /**
99  * Send an info request to a specific host. The response must be freed by the caller on success.
100  *
101  * ~~~~~~~~~~{.c}
102  * char* res = NULL;
103  * if ( aerospike_info_host(&as, &err, NULL, "127.0.0.1", 3000, "info", &res) != AEROSPIKE_OK ) {
104  * // handle error
105  * }
106  * else {
107  * // handle response
108  * free(res);
109  * res = NULL;
110  * }
111  * ~~~~~~~~~~
112  *
113  * If TLS is enabled, this function will only work if the hostname is also the TLS certificate name.
114  *
115  * @param as The aerospike instance to use for this operation.
116  * @param err The as_error to be populated if an error occurs.
117  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
118  * @param hostname The IP address or hostname to send the request to.
119  * @param port The port to send the request to.
120  * @param req The info request to send.
121  * @param res The response from the node. The response will be a NULL terminated string,
122  * allocated by the function, and must be freed by the caller.
123  *
124  * @return AEROSPIKE_OK on success. Otherwise an error.
125  *
126  * @ingroup info_operations
127  */
128 as_status
130  aerospike* as, as_error* err, const as_policy_info* policy, const char* hostname, uint16_t port,
131  const char* req, char** res
132  );
133 
134 /**
135  * Send an info request to a specific socket address. The response must be freed by the caller on success.
136  * This function does not support TLS connections nor IPv6.
137  *
138  * ~~~~~~~~~~{.c}
139  * char* res = NULL;
140  * if ( aerospike_info_socket_address(&as, &err, NULL, &sa_in, "info", &res) != AEROSPIKE_OK ) {
141  * // handle error
142  * }
143  * else {
144  * // handle response
145  * free(res);
146  * res = NULL;
147  * }
148  * ~~~~~~~~~~
149  *
150  * @param as The aerospike instance to use for this operation.
151  * @param err The as_error to be populated if an error occurs.
152  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
153  * @param sa_in The IP address and port to send the request to.
154  * @param req The info request to send.
155  * @param res The response from the node. The response will be a NULL terminated string,
156  * allocated by the function, and must be freed by the caller.
157  *
158  * @return AEROSPIKE_OK on success. Otherwise an error.
159  *
160  * @ingroup info_operations
161  */
162 as_status
164  aerospike* as, as_error* err, const as_policy_info* policy, struct sockaddr_in* sa_in,
165  const char* req, char** res
166  );
167 
168 /**
169  * Send an info request to a node in the cluster. If node request fails, send request to the next
170  * node in the cluster. Repeat until the node request succeeds. The response must be freed by
171  * the caller on success.
172  *
173  * ~~~~~~~~~~{.c}
174  * char* res = NULL;
175  * if ( aerospike_info_any(&as, &err, NULL, "info", &res) != AEROSPIKE_OK ) {
176  * // handle error
177  * }
178  * else {
179  * // handle response
180  * free(res);
181  * res = NULL;
182  * }
183  * ~~~~~~~~~~
184  *
185  * @param as The aerospike instance to use for this operation.
186  * @param err The as_error to be populated if an error occurs.
187  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
188  * @param req The info request to send.
189  * @param res The response from the node. The response will be a NULL terminated string,
190  * allocated by the function, and must be freed by the caller.
191  *
192  * @return AEROSPIKE_OK on success. Otherwise an error.
193  *
194  * @ingroup info_operations
195  */
196 as_status
198  aerospike* as, as_error* err, const as_policy_info* policy, const char* req, char** res
199  );
200 
201 /**
202  * Send an info request to the entire cluster.
203  *
204  * ~~~~~~~~~~{.c}
205  * if ( aerospike_info_foreach(&as, &err, NULL, "info", callback, NULL) != AEROSPIKE_OK ) {
206  * // handle error
207  * }
208  * ~~~~~~~~~~
209  *
210  * The callback takes a response string. The caller should not free this string.
211  *
212  * ~~~~~~~~~~{.c}
213  * bool callback(const as_error* err, const as_node * node, const char* req, char* res, void* udata) {
214  * // handle response
215  * }
216  * ~~~~~~~~~~
217  *
218  *
219  * @param as The aerospike instance to use for this operation.
220  * @param err The as_error to be populated if an error occurs.
221  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
222  * @param req The info request to send.
223  * @param callback The function to call when a response is received.
224  * @param udata User-data to send to the callback.
225  *
226  * @return AEROSPIKE_OK on success. Otherwise an error.
227  *
228  * @ingroup info_operations
229  */
230 as_status
232  aerospike* as, as_error* err, const as_policy_info* policy, const char* req,
233  aerospike_info_foreach_callback callback, void* udata
234  );
235 
236 #ifdef __cplusplus
237 } // end extern "C"
238 #endif
as_status aerospike_info_host(aerospike *as, as_error *err, const as_policy_info *policy, const char *hostname, uint16_t port, const char *req, char **res)
as_status
Definition: as_status.h:30
as_status aerospike_info_socket_address(aerospike *as, as_error *err, const as_policy_info *policy, struct sockaddr_in *sa_in, const char *req, char **res)
as_status aerospike_info_any(aerospike *as, as_error *err, const as_policy_info *policy, const char *req, char **res)
bool(* aerospike_info_foreach_callback)(const as_error *err, const as_node *node, const char *req, char *res, void *udata)
as_status aerospike_info_node(aerospike *as, as_error *err, const as_policy_info *policy, as_node *node, const char *req, char **res)
as_status aerospike_info_foreach(aerospike *as, as_error *err, const as_policy_info *policy, const char *req, aerospike_info_foreach_callback callback, void *udata)