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-2015 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 res The response to the info request.
53  * @param udata The udata provided to the aerospike_info_foreach()
54  *
55  * @return TRUE to continue to the next info response. FALSE to stop processing.
56  *
57  * @ingroup info_operations
58  */
59 typedef bool (* aerospike_info_foreach_callback)(const as_error * err, const as_node * node, const char * req, char * res, void * udata);
60 
61 /******************************************************************************
62  * FUNCTIONS
63  *****************************************************************************/
64 
65 /**
66  * Send an info request to a specific host. The response must be freed by the caller on success.
67  *
68  * ~~~~~~~~~~{.c}
69  * char * res = NULL;
70  * if ( aerospike_info_host(&as, &err, NULL, "127.0.0.1", 3000, "info", &res) != AEROSPIKE_OK ) {
71  * // handle error
72  * }
73  * else {
74  * // handle response
75  * free(res);
76  * res = NULL;
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 addr The IP address or hostname to send the request to.
84  * @param port The port to send the request to.
85  * @param req The info request to send.
86  * @param res The response from the node. The response will be a NULL terminated string, 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  */
93  aerospike * as, as_error * err, const as_policy_info * policy,
94  const char * addr, uint16_t port, const char * req,
95  char ** res
96  );
97 
98 /**
99  * Send an info request to a specific socket address. The response must be freed by the caller on success.
100  *
101  * ~~~~~~~~~~{.c}
102  * char * res = NULL;
103  * if ( aerospike_info_socket_address(&as, &err, NULL, &sa_in, "info", &res) != AEROSPIKE_OK ) {
104  * // handle error
105  * }
106  * else {
107  * // handle response
108  * free(res);
109  * res = NULL;
110  * }
111  * ~~~~~~~~~~
112  *
113  * @param as The aerospike instance to use for this operation.
114  * @param err The as_error to be populated if an error occurs.
115  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
116  * @param sa_in The IP address and 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, allocated by the function, and must be freed by the caller.
119  *
120  * @return AEROSPIKE_OK on success. Otherwise an error.
121  *
122  * @ingroup info_operations
123  */
125  aerospike * as, as_error * err, const as_policy_info * policy,
126  struct sockaddr_in* sa_in, const char * req,
127  char ** res
128  );
129 
130 /**
131  * Send an info request to a node in the cluster. If node request fails, send request to the next
132  * node in the cluster. Repeat until the node request succeeds. The response must be freed by
133  * the caller on success.
134  *
135  * ~~~~~~~~~~{.c}
136  * char * res = NULL;
137  * if ( aerospike_info_any(&as, &err, NULL, "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 req The info request to send.
151  * @param res The response from the node. The response will be a NULL terminated string, allocated by the function, and must be freed by the caller.
152  *
153  * @return AEROSPIKE_OK on success. Otherwise an error.
154  *
155  * @ingroup info_operations
156  */
158  aerospike * as, as_error * err, const as_policy_info * policy,
159  const char * req, char ** res
160  );
161 
162 /**
163  * Send an info request to the entire cluster.
164  *
165  * ~~~~~~~~~~{.c}
166  * if ( aerospike_info_foreach(&as, &err, NULL, "info", callback, NULL) != AEROSPIKE_OK ) {
167  * // handle error
168  * }
169  * ~~~~~~~~~~
170  *
171  * The callback takes a response string. The caller should not free this string.
172  *
173  * ~~~~~~~~~~{.c}
174  * bool callback(const as_error * err, const as_node * node, const char * req, char * res, void * udata) {
175  * // handle response
176  * }
177  * ~~~~~~~~~~
178  *
179  *
180  * @param as The aerospike instance to use for this operation.
181  * @param err The as_error to be populated if an error occurs.
182  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
183  * @param req The info request to send.
184  * @param callback The function to call when a response is received.
185  * @param udata User-data to send to the callback.
186  *
187  * @return AEROSPIKE_OK on success. Otherwise an error.
188  *
189  * @ingroup info_operations
190  */
192  aerospike * as, as_error * err, const as_policy_info * policy,
193  const char * req,
194  aerospike_info_foreach_callback callback, void * udata
195  );
196 
197 #ifdef __cplusplus
198 } // end extern "C"
199 #endif
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)
bool(* aerospike_info_foreach_callback)(const as_error *err, const as_node *node, const char *req, char *res, void *udata)
as_status aerospike_info_any(aerospike *as, as_error *err, const as_policy_info *policy, const char *req, char **res)
as_status aerospike_info_host(aerospike *as, as_error *err, const as_policy_info *policy, const char *addr, uint16_t port, 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)