All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_error.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 #include <aerospike/as_status.h>
20 #include <aerospike/as_string.h>
21 
22 #include <stdarg.h>
23 #include <stdint.h>
24 #include <stdio.h>
25 #include <string.h>
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 /******************************************************************************
32  * MACROS
33  *****************************************************************************/
34 
35 /**
36  * The size of as_error.message
37  *
38  * @ingroup as_error_object
39  */
40 #define AS_ERROR_MESSAGE_MAX_SIZE 1024
41 
42 /**
43  * The maximum string length of as_error.message
44  *
45  * @ingroup as_error_object
46  */
47 #define AS_ERROR_MESSAGE_MAX_LEN (AS_ERROR_MESSAGE_MAX_SIZE - 1)
48 
49 /******************************************************************************
50  * TYPES
51  *****************************************************************************/
52 
53 /**
54  * All operations that interact with the Aerospike cluster accept an as_error
55  * argument and return an as_status value. The as_error argument is populated
56  * with information about the error that occurred. The as_status return value
57  * is the as_error.code value.
58  *
59  * When an operation succeeds, the as_error.code value is usually set to
60  * `AEROSPIKE_OK`. There are some operations which may have other success
61  * status codes, so please review each operation for information on status
62  * codes.
63  *
64  * When as_error.code is not a success value (`AEROSPIKE_OK`), then you can
65  * expect the other fields of as_error.code to be populated.
66  *
67  * Example usage:
68  * ~~~~~~~~~~{.c}
69  * as_error err;
70  *
71  * if ( aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
72  * fprintf(stderr, "(%d) %s at %s[%s:%d]\n", error.code, err.message, err.func, err.file. err.line);
73  * }
74  * ~~~~~~~~~~
75  *
76  * You can reuse an as_error with multiple operations. Each operation
77  * internally resets the error. So, if an error occurred in one operation,
78  * and you did not check it, then the error will be lost with subsequent
79  * operations.
80  *
81  * Example usage:
82  *
83  * ~~~~~~~~~~{.c}
84  * as_error err;
85  *
86  * if ( aerospike_key_put(&as, &err, NULL, &key, rec) != AEROSPIKE_OK ) {
87  * fprintf(stderr, "(%d) %s at %s[%s:%d]\n", error.code, err.message, err.func, err.file. err.line);
88  * }
89  *
90  * if ( aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
91  * fprintf(stderr, "(%d) %s at %s[%s:%d]\n", error.code, err.message, err.func, err.file. err.line);
92  * }
93  * ~~~~~~~~~~
94  *
95  * @ingroup client_objects
96  */
97 typedef struct as_error_s {
98 
99  /**
100  * Numeric error code
101  */
103 
104  /**
105  * NULL-terminated error message
106  */
108 
109  /**
110  * Name of the function where the error occurred.
111  */
112  const char * func;
113 
114  /**
115  * Name of the file where the error occurred.
116  */
117  const char * file;
118 
119  /**
120  * Line in the file where the error occurred.
121  */
122  uint32_t line;
123 
124 } as_error;
125 
126 /******************************************************************************
127  * MACROS
128  *****************************************************************************/
129 
130 /**
131  * as_error_update(&as->error, AEROSPIKE_OK, "%s %d", "a", 1);
132  *
133  * @ingroup as_error_object
134  */
135 #define as_error_update(__err, __code, __fmt, ...) \
136  as_error_setallv( __err, __code, __func__, __FILE__, __LINE__, __fmt, ##__VA_ARGS__ );
137 
138 /**
139  * as_error_set_message(&as->error, AEROSPIKE_ERR, "error message");
140  *
141  * @ingroup as_error_object
142  */
143 #define as_error_set_message(__err, __code, __msg) \
144  as_error_setall( __err, __code, __msg, __func__, __FILE__, __LINE__ );
145 
146 /******************************************************************************
147  * FUNCTIONS
148  *****************************************************************************/
149 
150 /**
151  * Initialize the error to default (empty) values, returning the error.
152  *
153  * @param err The error to initialize.
154  *
155  * @returns The initialized err.
156  *
157  * @relates as_error
158  * @ingroup as_error_object
159  */
160 static inline as_error * as_error_init(as_error * err) {
161  err->code = AEROSPIKE_OK;
162  err->message[0] = '\0';
163  err->func = NULL;
164  err->file = NULL;
165  err->line = 0;
166  return err;
167 }
168 
169 /**
170  * Resets the error to default (empty) values, returning the status code.
171  *
172  * @param err The error to reset.
173  *
174  * @returns AEROSPIKE_OK.
175  *
176  * @relates as_error
177  * @ingroup as_error_object
178  */
179 static inline as_status as_error_reset(as_error * err) {
180  err->code = AEROSPIKE_OK;
181  err->message[0] = '\0';
182  err->func = NULL;
183  err->file = NULL;
184  err->line = 0;
185  return err->code;
186 }
187 
188 /**
189  * Sets the error.
190  *
191  * @return The status code set for the error.
192  *
193  * @relates as_error
194  */
195 static inline as_status as_error_setall(as_error * err, as_status code, const char * message, const char * func, const char * file, uint32_t line) {
196  err->code = code;
198  err->func = func;
199  err->file = file;
200  err->line = line;
201  return err->code;
202 }
203 
204 /**
205  * Sets the error.
206  *
207  * @return The status code set for the error.
208  *
209  * @relates as_error
210  */
211 static inline as_status as_error_setallv(as_error * err, as_status code, const char * func, const char * file, uint32_t line, const char * fmt, ...) {
212  if ( fmt != NULL ) {
213  va_list ap;
214  va_start(ap, fmt);
215  vsnprintf(err->message, AS_ERROR_MESSAGE_MAX_LEN, fmt, ap);
216  err->message[AS_ERROR_MESSAGE_MAX_LEN] = '\0';
217  va_end(ap);
218  }
219  err->code = code;
220  err->func = func;
221  err->file = file;
222  err->line = line;
223  return err->code;
224 }
225 
226 /**
227  * Sets the error message
228  *
229  * @relates as_error
230  */
231 static inline as_status as_error_set(as_error * err, as_status code, const char * fmt, ...) {
232  if ( fmt != NULL ) {
233  va_list ap;
234  va_start(ap, fmt);
235  vsnprintf(err->message, AS_ERROR_MESSAGE_MAX_LEN, fmt, ap);
236  err->message[AS_ERROR_MESSAGE_MAX_LEN] = '\0';
237  va_end(ap);
238  }
239  err->code = code;
240  return err->code;
241 }
242 
243 /**
244  * Copy error from source to target.
245  *
246  * @relates as_error
247  */
248 static inline void as_error_copy(as_error * trg, as_error * src) {
249  trg->code = src->code;
250  strcpy(trg->message, src->message);
251  trg->func = src->func;
252  trg->file = src->file;
253  trg->line = src->line;
254 }
255 
256 /**
257  * Return string representation of error code. Result should not be freed.
258  *
259  * @relates as_error
260  */
261 char*
262 as_error_string(as_status status);
263 
264 #ifdef __cplusplus
265 } // end extern "C"
266 #endif
#define AS_ERROR_MESSAGE_MAX_LEN
Definition: as_error.h:47
as_status
Definition: as_status.h:30
char message[AS_ERROR_MESSAGE_MAX_SIZE]
Definition: as_error.h:107
bool as_strncpy(char *trg, const char *src, int size)
char * as_error_string(as_status status)
const char * file
Definition: as_error.h:117
static as_error * as_error_init(as_error *err)
Definition: as_error.h:160
const char * func
Definition: as_error.h:112
static as_status as_error_set(as_error *err, as_status code, const char *fmt,...)
Definition: as_error.h:231
#define AS_ERROR_MESSAGE_MAX_SIZE
Definition: as_error.h:40
static as_status as_error_reset(as_error *err)
Definition: as_error.h:179
uint32_t line
Definition: as_error.h:122
as_status code
Definition: as_error.h:102
static void as_error_copy(as_error *trg, as_error *src)
Definition: as_error.h:248
static as_status as_error_setallv(as_error *err, as_status code, const char *func, const char *file, uint32_t line, const char *fmt,...)
Definition: as_error.h:211
static as_status as_error_setall(as_error *err, as_status code, const char *message, const char *func, const char *file, uint32_t line)
Definition: as_error.h:195