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-2017 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 server node(s) for statistics and set dynamically
24  * configurable variables.
25  */
26 
27 #include <aerospike/aerospike.h>
29 #include <aerospike/as_error.h>
30 #include <aerospike/as_node.h>
31 #include <aerospike/as_policy.h>
32 #include <aerospike/as_status.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /******************************************************************************
39  * TYPES
40  *****************************************************************************/
41 
42 /**
43  * Callback for aerospike_info_foreach()
44  *
45  * @param err The status and possible error information for the info request.
46  * @param node The node which provided the response.
47  * @param req The initial request.
48  * @param res The response to the info request.
49  * @param udata The udata provided to the aerospike_info_foreach()
50  *
51  * @return TRUE to continue to the next info response. FALSE to stop processing.
52  *
53  * @ingroup info_operations
54  */
55 typedef bool (*aerospike_info_foreach_callback)(const as_error* err, const as_node* node, const char* req, char* res, void* udata);
56 
57 /******************************************************************************
58  * FUNCTIONS
59  *****************************************************************************/
60 
61 /**
62  * Send an info request to a specific server node. The response must be freed by the caller on success.
63  *
64  * ~~~~~~~~~~{.c}
65  * char* res = NULL;
66  * if (aerospike_info_node(&as, &err, NULL, node, "info", &res) != AEROSPIKE_OK) {
67  * // handle error
68  * }
69  * else {
70  * // handle response
71  * free(res);
72  * }
73  * ~~~~~~~~~~
74  *
75  * @param as The aerospike instance to use for this operation.
76  * @param err The as_error to be populated if an error occurs.
77  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
78  * @param node The server node to send the request to.
79  * @param req The info request to send.
80  * @param res The response from the node. The response will be a NULL terminated string,
81  * allocated by the function, and must be freed by the caller.
82  *
83  * @return AEROSPIKE_OK on success. Otherwise an error.
84  *
85  * @ingroup info_operations
86  */
89  aerospike* as, as_error* err, const as_policy_info* policy, as_node* node,
90  const char* req, char** res
91  );
92 
93 /**
94  * Send an info request to a specific host. The response must be freed by the caller on success.
95  *
96  * ~~~~~~~~~~{.c}
97  * char* res = NULL;
98  * if (aerospike_info_host(&as, &err, NULL, "127.0.0.1", 3000, "info", &res) != AEROSPIKE_OK) {
99  * // handle error
100  * }
101  * else {
102  * // handle response
103  * free(res);
104  * res = NULL;
105  * }
106  * ~~~~~~~~~~
107  *
108  * If TLS is enabled, this function will only work if the hostname is also the TLS certificate name.
109  *
110  * @deprecated Use aerospike_info_node() or aerospike_info_any() instead.
111  *
112  * @param as The aerospike instance to use for this operation.
113  * @param err The as_error to be populated if an error occurs.
114  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
115  * @param hostname The IP address or hostname to send the request to.
116  * @param port The port to send the request to.
117  * @param req The info request to send.
118  * @param res The response from the node. The response will be a NULL terminated string,
119  * allocated by the function, and must be freed by the caller.
120  *
121  * @return AEROSPIKE_OK on success. Otherwise an error.
122  *
123  * @ingroup info_operations
124  */
125 as_status
127  aerospike* as, as_error* err, const as_policy_info* policy, const char* hostname, uint16_t port,
128  const char* req, char** res
129  );
130 
131 /**
132  * Send an info request to a specific socket address. The response must be freed by the caller on success.
133  * This function does not support TLS connections nor IPv6.
134  *
135  * ~~~~~~~~~~{.c}
136  * char* res = NULL;
137  * if (aerospike_info_socket_address(&as, &err, NULL, &sa_in, "info", &res) != AEROSPIKE_OK) {
138  * // handle error
139  * }
140  * else {
141  * // handle response
142  * free(res);
143  * res = NULL;
144  * }
145  * ~~~~~~~~~~
146  *
147  * @param as The aerospike instance to use for this operation.
148  * @param err The as_error to be populated if an error occurs.
149  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
150  * @param sa_in The IP address and port to send the request to.
151  * @param req The info request to send.
152  * @param res The response from the node. The response will be a NULL terminated string,
153  * allocated by the function, and must be freed by the caller.
154  *
155  * @return AEROSPIKE_OK on success. Otherwise an error.
156  *
157  * @ingroup info_operations
158  */
159 as_status
161  aerospike* as, as_error* err, const as_policy_info* policy, struct sockaddr_in* sa_in,
162  const char* req, char** res
163  );
164 
165 /**
166  * Send an info request to a node in the cluster. If node request fails, send request to the next
167  * node in the cluster. Repeat until the node request succeeds. The response must be freed by
168  * the caller on success.
169  *
170  * ~~~~~~~~~~{.c}
171  * char* res = NULL;
172  * if (aerospike_info_any(&as, &err, NULL, "info", &res) != AEROSPIKE_OK) {
173  * // handle error
174  * }
175  * else {
176  * // handle response
177  * free(res);
178  * res = NULL;
179  * }
180  * ~~~~~~~~~~
181  *
182  * @param as The aerospike instance to use for this operation.
183  * @param err The as_error to be populated if an error occurs.
184  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
185  * @param req The info request to send.
186  * @param res The response from the node. The response will be a NULL terminated string,
187  * allocated by the function, and must be freed by the caller.
188  *
189  * @return AEROSPIKE_OK on success. Otherwise an error.
190  *
191  * @ingroup info_operations
192  */
193 as_status
195  aerospike* as, as_error* err, const as_policy_info* policy, const char* req, char** res
196  );
197 
198 /**
199  * Send an info request to the entire cluster.
200  *
201  * ~~~~~~~~~~{.c}
202  * if (aerospike_info_foreach(&as, &err, NULL, "info", callback, NULL) != AEROSPIKE_OK) {
203  * // handle error
204  * }
205  * ~~~~~~~~~~
206  *
207  * The callback takes a response string. The caller should not free this string.
208  *
209  * ~~~~~~~~~~{.c}
210  * bool callback(const as_error* err, const as_node * node, const char* req, char* res, void* udata) {
211  * // handle response
212  * }
213  * ~~~~~~~~~~
214  *
215  *
216  * @param as The aerospike instance to use for this operation.
217  * @param err The as_error to be populated if an error occurs.
218  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
219  * @param req The info request to send.
220  * @param callback The function to call when a response is received.
221  * @param udata User-data to send to the callback.
222  *
223  * @return AEROSPIKE_OK on success. Otherwise an error.
224  *
225  * @ingroup info_operations
226  */
227 as_status
229  aerospike* as, as_error* err, const as_policy_info* policy, const char* req,
230  aerospike_info_foreach_callback callback, void* udata
231  );
232 
233 #ifdef __cplusplus
234 } // end extern "C"
235 #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)