AMXX-BG.INFO › grip.inc › Raw include

grip.inc

Original include source with line numbers.

Back Download .inc
1 /*
2 * gRIP
3 * Copyright (c) 2018 Alik Aslanyan <[email protected]>
4 * Copyright (C) The AMX Mod X Development Team.
5 *
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 3 of the License, or (at
10 * your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software Foundation,
19 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 *
21 * In addition, as a special exception, the author gives permission to
22 * link the code of this program with the Half-Life Game Engine ("HL
23 * Engine") and Modified Game Libraries ("MODs") developed by Valve,
24 * L.L.C ("Valve"). You must obey the GNU General Public License in all
25 * respects for all of the code used other than the HL Engine and MODs
26 * from Valve. If you modify this file, you may extend this exception
27 * to your version of the file, but you are not obligated to do so. If
28 * you do not wish to do so, delete this exception statement from your
29 * version.
30 *
31 */
32
33 /*
34 * Some of the API definitions were taken from AMX Mod X. There are places, where I decided to do somethings differently.
35 * Btw JSON implementation is designed to be 90% drop in replacement of AMX Mod X json.inc file.
36 */
37
38 #if defined _grip_included
39 #endinput
40 #endif
41 #define _grip_included
42
43 #pragma reqlib grip
44 #if !defined AMXMODX_NOAUTOLOAD
45 #pragma loadlib grip
46 #endif
47
48
49 enum GripRequestType {
50 GripRequestTypeGet = 0,
51 GripRequestTypePost = 1,
52 GripRequestTypePut = 2,
53 GripRequestTypeDelete = 3
54 }
55
56 enum GripRequestCancellation {
57 Invalid_GripRequestCancellation = 0,
58 }
59
60 enum GripRequestOptions {
61 Empty_GripRequestOptions = -1,
62 Invalid_GripRequestOptions = 0,
63 }
64
65 enum GripBody {
66 Empty_GripBody = -1,
67 Invalid_GripBody = 0,
68 }
69
70 enum GripJSONValue {
71 Invalid_GripJSONValue = 0,
72 }
73
74 /*
75 * JSON types
76 */
77 enum GripJSONType
78 {
79 GripJSONNull = 1,
80 GripJSONString = 2,
81 GripJSONNumber = 3,
82 GripJSONObject = 4,
83 GripJSONArray = 5,
84 GripJSONBoolean = 6,
85 GripJSONError = 7,
86 };
87
88 enum GripResponseState {
89 GripResponseStateCancelled = 1,
90 GripResponseStateError = 2,
91 GripResponseStateSuccessful = 3,
92 GripResponseStateTimeout = 4,
93 }
94
95 enum GripHTTPStatus {
96 GripHTTPStatusContinue = 100,
97 GripHTTPStatusSwitchingProtocols = 101,
98 GripHTTPStatusProcessing = 102,
99 GripHTTPStatusOk = 200,
100 GripHTTPStatusCreated = 201,
101 GripHTTPStatusAccepted = 202,
102 GripHTTPStatusNonAuthoritativeInformation = 203,
103 GripHTTPStatusNoContent = 204,
104 GripHTTPStatusResetContent = 205,
105 GripHTTPStatusPartialContent = 206,
106 GripHTTPStatusMultiStatus = 207,
107 GripHTTPStatusAlreadyReported = 208,
108 GripHTTPStatusImUsed = 226,
109 GripHTTPStatusMultipleChoices = 300,
110 GripHTTPStatusMovedPermanently = 301,
111 GripHTTPStatusFound = 302,
112 GripHTTPStatusSeeOther = 303,
113 GripHTTPStatusNotModified = 304,
114 GripHTTPStatusUseProxy = 305,
115 GripHTTPStatusTemporaryRedirect = 307,
116 GripHTTPStatusPermanentRedirect = 308,
117 GripHTTPStatusBadRequest = 400,
118 GripHTTPStatusUnauthorized = 401,
119 GripHTTPStatusPaymentRequired = 402,
120 GripHTTPStatusForbidden = 403,
121 GripHTTPStatusNotFound = 404,
122 GripHTTPStatusMethodNotAllowed = 405,
123 GripHTTPStatusNotAcceptable = 406,
124 GripHTTPStatusProxyAuthenticationRequired = 407,
125 GripHTTPStatusRequestTimeout = 408,
126 GripHTTPStatusConflict = 409,
127 GripHTTPStatusGone = 410,
128 GripHTTPStatusLengthRequired = 411,
129 GripHTTPStatusPreconditionFailed = 412,
130 GripHTTPStatusPayloadTooLarge = 413,
131 GripHTTPStatusUriTooLong = 414,
132 GripHTTPStatusUnsupportedMediaType = 415,
133 GripHTTPStatusRangeNotSatisfiable = 416,
134 GripHTTPStatusExpectationFailed = 417,
135 GripHTTPStatusImATeapot = 418,
136 GripHTTPStatusMisdirectedRequest = 421,
137 GripHTTPStatusUnprocessableEntity = 422,
138 GripHTTPStatusLocked = 423,
139 GripHTTPStatusFailedDependency = 424,
140 GripHTTPStatusUpgradeRequired = 426,
141 GripHTTPStatusPreconditionRequired = 428,
142 GripHTTPStatusTooManyRequests = 429,
143 GripHTTPStatusRequestHeaderFieldsTooLarge = 431,
144 GripHTTPStatusUnavailableForLegalReasons = 451,
145 GripHTTPStatusInternalServerError = 500,
146 GripHTTPStatusNotImplemented = 501,
147 GripHTTPStatusBadGateway = 502,
148 GripHTTPStatusServiceUnavailable = 503,
149 GripHTTPStatusGatewayTimeout = 504,
150 GripHTTPStatusHttpVersionNotSupported = 505,
151 GripHTTPStatusVariantAlsoNegotiates = 506,
152 GripHTTPStatusInsufficientStorage = 507,
153 GripHTTPStatusLoopDetected = 508,
154 GripHTTPStatusNotExtended = 510,
155 GripHTTPStatusNetworkAuthenticationRequired = 511,
156 };
157
158 /**
159 * Gets state of the response.
160 *
161 * @note This has nothing to do with HTTP status codes.
162 *
163 * @return Returns current response state.
164 */
165 native GripResponseState:grip_get_response_state();
166
167
168 /**
169 * Gets HTTP status code of the response.
170 *
171 * @return Returns current response state.
172 */
173 native any:grip_get_response_status_code();
174
175 /**
176 * Returns whether request exists/active.
177 *
178 * @note This has nothing to do with HTTP status codes.
179 *
180 * @param request Request handle.
181 *
182 * @return Returns current response state.
183 */
184 native grip_is_request_active(GripRequestCancellation:request);
185
186 /**
187 * Creates new body handle from string
188 *
189 * @note Body should be destroyed with the relevant call.
190 *
191 * @param str Zero terminated string from which body should be created
192 *
193 * @return Newly crated body handle
194 */
195 native GripBody:grip_body_from_string(str[]);
196
197 /**
198 * Creates new body handle from string
199 *
200 * @note Body should be destroyed with the relevant call.
201 *
202 * @param str Zero terminated string from which body should be created
203 * @param pretty True to format pretty JSON string, false to not
204 * @param recursion_limit Limit of the internal recursion
205 *
206 * @return Newly crated body handle
207 */
208 native GripBody:grip_body_from_json(GripJSONValue:value, bool:pretty = false, recursion_limit = 100);
209
210 /**
211 * Destroys body handle
212 *
213 * @param body Body to be destroyed
214 *
215 * @noreturn
216 */
217 native grip_destroy_body(GripBody:body);
218
219 /**
220 * Starts sending of the request
221 * @note The handle should look like:
222 * public RequestHandler(const any: userData);
223 *
224 *
225 * @param uri Request URI. Supports TLS.
226 * @param type Request type which should be sended.
227 * @param body Reqeust body, can be either JSON or plaintext
228 * @param handler A callback which will be called when request finishes execution
229 * @param options Request options containing HTTP headers, timeout and so on..
230 * @param userData User data (can be datapack or anything)
231 *
232 * @return Cancellation handle.
233 */
234 native GripRequestCancellation:grip_request(const uri[], GripBody:body, GripRequestType:type, const handler[], GripRequestOptions:options = Empty_GripRequestOptions, const any: userData = 0);
235
236 /**
237 * Cancel sending of the request and receiving of response.
238 *
239 * @param cancellation Cancellation handle of the request.
240 *
241 * @return Request handle
242 */
243 native grip_cancel_request(GripRequestCancellation:cancellation);
244
245 /**
246 * Get current error description. Implementation defined.
247 *
248 * @note There are certain AMXX limitations to maximum string sizes.
249 *
250 * @param buffer Output buffer to which description should be written
251 * @param buffer_size Maximum length of the buffer.
252 *
253 * @return Number of cells written
254 */
255 native grip_get_error_description(buffer[], buffer_size);
256
257 /**
258 * Get current response body as string.
259 *
260 * @note There are certain AMXX limitations to maximum string sizes.
261 *
262 * @param buffer Output buffer to which body should be written
263 * @param buffer_size Maximum length of the buffer.
264 *
265 * @return Number of cells written
266 */
267 native grip_get_response_body_string(buffer[], buffer_size);
268
269 /**
270 * Destroy this JSON value
271 *
272 * @param json_value JSON Value to be destroyed.
273 *
274 * @noreturn
275 */
276 native grip_destroy_json_value(GripJSONValue:grip_json_value);
277
278 /**
279 * Create options with empty headers and some timeout.
280 *
281 * @note Options should be destroyed with the relevant call.
282 *
283 * @param timeout timeout -1 to disable, >0 to enable timeout.
284 *
285 * @return Request options handle.
286 */
287 native GripRequestOptions:grip_create_default_options(Float:timeout = -1.0);
288
289 /**
290 * Destroy this options
291 *
292 * @noreturn
293 */
294 native grip_destroy_options(GripRequestOptions:options);
295
296 /**
297 * Add HTTP Header to this options.
298 *.
299 * @param options Options to which header should be added
300 * @param headerName Header name
301 * @param headerValue Header value
302 *
303 * @return Request options handle.
304 */
305 native grip_options_add_header(GripRequestOptions:options, const headerName[], const headerValue[]);
306
307
308 /**
309 * Create options with headers and some timeout.
310 *
311 * @note Options should be destroyed with the relevant call.
312 *
313 * @param headers Array of header pairs.
314 * @param headers_count Count of the header pairs.
315 * @param timeout timeout -1 to disable, >0 to enable timeout.
316 *
317 * @return Request options handle.
318 */
319 stock grip_create_options(const headers[][2][], const headers_count, Float:timeout = -1.0) {
320 new GripRequestOptions:options = grip_create_default_options(timeout);
321
322 for(new i = 0; i < headers_count; ++i) {
323 grip_options_add_header(options, headers[i][0], headers[i][1]);
324 }
325
326 return options;
327 }
328
329 /**
330 * Parse current response body as JSON.
331 *
332 * @param buffer Output buffer to which possible error should be written
333 * @param error_buffer_size Maximum length of the buffer.
334 *
335 *
336 * @return JSON Value handle. If error occurred, returns invalid handle.
337 */
338 native GripJSONValue:grip_json_parse_response_body(error_buffer[], const error_buffer_size);
339
340 /**
341 * Parses string that contains JSON.
342 *
343 * @note Needs to be destroyed using grip_destroy_json_value() native.
344 *
345 * @param string String to parse
346 * @param buffer Output buffer to which possible error should be written
347 * @param error_buffer_size Maximum length of the buffer.
348 *
349 * @return JSON value, Invalid_GripJSONValue if error occurred
350 */
351 native GripJSONValue:grip_json_parse_string(const string[], error_buffer[], const error_buffer_size);
352
353 /**
354 * Parses file that contains JSON.
355 *
356 * @note Needs to be destroyed using grip_destroy_json_value() native.
357 *
358 * @param string String to parse
359 *
360 * @return JSON value, Invalid_GripJSONValue if error occurred
361 */
362 native GripJSONValue:grip_json_parse_file(const file[], error_buffer[], const error_buffer_size);
363
364 /**
365 * Checks if the first value is the same as the second one.
366 *
367 * @param value1 JSON handle
368 * @param value2 JSON handle
369 *
370 * @return True if they are the same, false otherwise
371 * @error If passed value is not a valid handle
372 */
373 native bool:grip_json_equals(const GripJSONValue:value1, const GripJSONValue:value2);
374
375 /**
376 * Validates json by checking if object have identically named
377 * fields with matching types.
378 *
379 * @note Schema {"name":"", "age":0} will validate
380 * {"name":"Joe", "age":25} and {"name":"Joe", "age":25, "gender":"m"},
381 * but not {"name":"Joe"} or {"name":"Joe", "age":"Cucumber"}.
382 *
383 * @note In case of arrays, only first value in schema
384 * is checked against all values in tested array.
385 *
386 * @note Empty objects ({}) validate all objects,
387 * empty arrays ([]) validate all arrays,
388 * null validates values of every type.
389 *
390 * @param schema JSON handle
391 * @param value JSON handle
392 *
393 * @return True if passed value is valid, false otherwise
394 * @error If a schema handle or value handle is invalid
395 */
396 native bool:grip_json_validate(const GripJSONValue:schema, const GripJSONValue:value);
397
398 /**
399 * Gets value's parent handle.
400 *
401 * @note Parent's handle Needs to be destroyed using grip_destroy_json_value() native.
402 *
403 * @param value JSON handle
404 *
405 * @return Parent's handle
406 */
407 // This method is wontfix, because of mixed value/ref semantics of json.inc
408 // native GripJSONValue:grip_json_get_parent(const GripJSONValue:value);
409
410 /**
411 * Gets JSON type of passed value.
412 *
413 * @param value JSON handle
414 *
415 * @return JSON type (GripJSONType constants)
416 * @error If a value handle is invalid
417 */
418 native GripJSONType:grip_json_get_type(const GripJSONValue:value);
419
420 /**
421 * Inits an empty object.
422 *
423 * @note Needs to be destroyed using grip_destroy_json_value() native.
424 *
425 * @return JSON handle, Invalid_GripJSONValue if error occurred
426 */
427 native GripJSONValue:grip_json_init_object();
428
429 /**
430 * Inits an empty array.
431 *
432 * @note Needs to be destroyed using grip_destroy_json_value() native.
433 *
434 * @return JSON handle, Invalid_GripJSONValue if error occurred
435 */
436 native GripJSONValue:grip_json_init_array();
437
438 /**
439 * Inits string data.
440 *
441 * @note Needs to be destroyed using grip_destroy_json_value() native.
442 *
443 * @param value String that the handle will be initialized with
444 *
445 * @return JSON handle, Invalid_GripJSONValue if error occurred
446 */
447 native GripJSONValue:grip_json_init_string(const value[]);
448
449 /**
450 * Inits a number.
451 *
452 * @note Needs to be destroyed using grip_destroy_json_value() native.
453 *
454 * @param value Integer number that the handle will be initialized with
455 *
456 * @return JSON handle, Invalid_GripJSONValue if error occurred
457 */
458 native GripJSONValue:grip_json_init_number(value);
459
460 /**
461 * Inits a float number.
462 *
463 * @note Needs to be destroyed using grip_destroy_json_value() native.
464 *
465 * @param value Float number that the handle will be initialized with
466 *
467 * @return JSON handle, Invalid_GripJSONValue if error occurred
468 */
469 native GripJSONValue:grip_json_init_float(Float:value);
470 #define grip_json_init_real(%1) grip_json_init_float(%1)
471
472 /**
473 * Inits a boolean value.
474 *
475 * @note Needs to be destroyed using grip_destroy_json_value() native.
476 *
477 * @param value Boolean value that the handle will be initialized with
478 *
479 * @return JSON handle, Invalid_GripJSONValue if error occurred
480 */
481 native GripJSONValue:grip_json_init_bool(bool:value);
482
483 /**
484 * Inits a null.
485 *
486 * @note Needs to be destroyed using grip_destroy_json_value() native.
487 *
488 * @return JSON handle, Invalid_GripJSONValue if error occurred
489 */
490 native GripJSONValue:grip_json_init_null();
491
492 /**
493 * Creates deep copy of passed value.
494 *
495 * @note Needs to be destroyed using grip_destroy_json_value() native.
496 *
497 * @param value JSON handle to be copied
498 *
499 * @return JSON handle, Invalid_GripJSONValue if error occurred
500 * @error If passed value is not a valid handle
501 */
502 native GripJSONValue:grip_json_deep_copy(const GripJSONValue:value);
503
504 /**
505 * Gets string data.
506 *
507 * @param value JSON handle
508 * @param buffer Buffer to copy string to
509 * @param maxlen Maximum size of the buffer
510 *
511 * @return The number of cells written to the buffer
512 * @error If passed value is not a valid handle
513 */
514 native grip_json_get_string(const GripJSONValue:value, buffer[], maxlen);
515
516 /**
517 * Gets a number.
518 *
519 * @param value JSON handle
520 *
521 * @return Number
522 * @error If passed value is not a valid handle
523 */
524 native grip_json_get_number(const GripJSONValue:value);
525
526 /**
527 * Gets a float number.
528 *
529 * @param value JSON handle
530 *
531 * @return Real number
532 * @error If passed value is not a valid handle
533 */
534 #define grip_json_get_real(%1) grip_json_get_float(%1)
535 native Float:grip_json_get_float(const GripJSONValue:value);
536
537 /**
538 * Gets a boolean value.
539 *
540 * @param value JSON handle
541 *
542 * @return Boolean value
543 * @error If passed value is not a valid handle
544 */
545 native bool:grip_json_get_bool(const GripJSONValue:value);
546
547 /**
548 * Gets a value from the array.
549 *
550 * @note Needs to be destroyed using grip_destroy_json_value() native.
551 *
552 * @param array Array handle
553 * @param index Position in the array (starting from 0)
554 *
555 * @return JSON handle, Invalid_GripJSONValue if error occurred
556 * @error If passed handle is not a valid array
557 */
558 native GripJSONValue:grip_json_array_get_value(const GripJSONValue:array, index);
559
560 /**
561 * Gets string data from the array.
562 *
563 * @param array Array handle
564 * @param index Position in the array (starting from 0)
565 * @param buffer Buffer to copy string to
566 * @param maxlen Maximum size of the buffer
567 *
568 * @return The number of cells written to the buffer
569 * @error If passed handle is not a valid array
570 */
571 native grip_json_array_get_string(const GripJSONValue:array, index, buffer[], buffer_size);
572
573 /**
574 * Gets a number from the array.
575 *
576 * @param array Array handle
577 * @param index Position in the array (starting from 0)
578 *
579 * @return The number as integer
580 * @error If passed handle is not a valid array
581 */
582 native grip_json_array_get_number(const GripJSONValue:array, index);
583
584 /**
585 * Gets a real number from the array.
586 *
587 * @param array Array handle
588 * @param index Position in the array (starting from 0)
589 *
590 * @return The number as float
591 * @error If passed handle is not a valid array
592 */
593 #define grip_json_array_get_real(%1, %2) grip_json_array_get_float(%1, %2)
594 native Float:grip_json_array_get_float(const GripJSONValue:array, index);
595
596 /**
597 * Gets a boolean value from the array.
598 *
599 * @param array Array handle
600 * @param index Position in the array (starting from 0)
601 *
602 * @return Boolean value
603 * @error If passed handle is not a valid array
604 */
605 native bool:grip_json_array_get_bool(const GripJSONValue:array, index);
606
607 /**
608 * Gets count of the elements in the array.
609 *
610 * @param array Array handle
611 *
612 * @return Number of elements in the array
613 * @error If passed handle is not a valid array
614 */
615 native grip_json_array_get_count(const GripJSONValue:array);
616
617 /**
618 * Replaces an element in the array with value.
619 *
620 * @param array Array handle
621 * @param index Position in the array to be replaced
622 * @param value JSON handle to set
623 *
624 * @return True if succeed, false otherwise
625 * @error If passed handle is not a valid array
626 */
627 native bool:grip_json_array_replace_value(GripJSONValue:array, index, const GripJSONValue:value);
628
629 /**
630 * Replaces an element in the array with string data.
631 *
632 * @param array Array handle
633 * @param index Position in the array to be replaced
634 * @param string String to copy
635 *
636 * @return True if succeed, false otherwise
637 * @error If passed handle is not a valid array
638 */
639 native bool:grip_json_array_replace_string(GripJSONValue:array, index, const string[]);
640
641 /**
642 * Replaces an element in the array with number.
643 *
644 * @param array Array handle
645 * @param index Position in the array to be replaced
646 * @param number Number to set
647 *
648 * @return True if succeed, false otherwise
649 * @error If passed handle is not a valid array
650 */
651 native bool:grip_json_array_replace_number(GripJSONValue:array, index, number);
652
653 /**
654 * Replaces an element in the array with real number.
655 *
656 * @param array Array handle
657 * @param index Position in the array to be replaced
658 * @param number Real number to set
659 *
660 * @return True if succeed, false otherwise
661 * @error If passed handle is not a valid array
662 */
663 native bool:grip_json_array_replace_float(GripJSONValue:array, index, Float:number);
664 #define grip_json_array_replace_real(%1, %2, %2) grip_json_array_replace_float(%1, %2, %3)
665
666 /**
667 * Replaces an element in the array with boolean value.
668 *
669 * @param array Array handle
670 * @param index Position in the array to be replaced
671 * @param boolean Boolean value to set
672 *
673 * @return True if succeed, false otherwise
674 * @error If passed handle is not a valid array
675 */
676 native bool:grip_json_array_replace_bool(GripJSONValue:array, index, bool:boolean);
677
678 /**
679 * Replaces an element in the array with null.
680 *
681 * @param array Array handle
682 * @param index Position in the array to be replaced
683 *
684 * @return True if succeed, false otherwise
685 * @error If passed handle is not a valid array
686 */
687 native bool:grip_json_array_replace_null(GripJSONValue:array, index);
688
689 /**
690 * Appends a value in the array.
691 *
692 * @param array Array handle
693 * @param value JSON handle to set
694 *
695 * @return True if succeed, false otherwise
696 * @error If passed handle is not a valid array
697 */
698 native bool:grip_json_array_append_value(GripJSONValue:array, const GripJSONValue:value);
699
700 /**
701 * Appends string data in the array.
702 *
703 * @param array Array handle
704 * @param string String to copy
705 *
706 * @return True if succeed, false otherwise
707 * @error If passed handle is not a valid array
708 */
709 native bool:grip_json_array_append_string(GripJSONValue:array, const string[]);
710
711 /**
712 * Appends a number in the array.
713 *
714 * @param array Array handle
715 * @param number Number to set
716 *
717 * @return True if succeed, false otherwise
718 * @error If passed handle is not a valid array
719 */
720 native bool:grip_json_array_append_number(GripJSONValue:array, number);
721
722 /**
723 * Appends a real number in the array.
724 *
725 * @param array Array handle
726 * @param number Real number to set
727 *
728 * @return True if succeed, false otherwise
729 * @error If passed handle is not a valid array
730 */
731 native bool:grip_json_array_append_float(GripJSONValue:array, Float:number);
732 #define grip_json_array_append_real(%1, %2, %3) grip_json_array_append_float(%1, %2, %3)
733
734 /**
735 * Appends a boolean value in the array.
736 *
737 * @param array Array handle
738 * @param boolean Boolean value to set
739 *
740 * @return True if succeed, false otherwise
741 * @error If passed handle is not a valid array
742 */
743 native bool:grip_json_array_append_bool(GripJSONValue:array, bool:boolean);
744
745 /**
746 * Appends a null in the array.
747 *
748 * @param array Array handle
749 *
750 * @return True if succeed, false otherwise
751 * @error If passed handle is not a valid array
752 */
753 native bool:grip_json_array_append_null(GripJSONValue:array);
754
755 /**
756 * Removes an element from the array.
757 *
758 * @note Order of values in array may change during execution.
759 *
760 * @param array Array handle
761 * @param index Position in the array (starting from 0)
762 *
763 * @return True if succeed, false otherwise
764 * @error If passed handle is not a valid array
765 */
766 native bool:grip_json_array_remove(GripJSONValue:array, index);
767
768 /**
769 * Removes all elements from the array.
770 *
771 * @param array Array handle
772 *
773 * @return True if succeed, false otherwise
774 * @error If passed handle is not a valid array
775 */
776 native bool:grip_json_array_clear(GripJSONValue:array);
777
778 /**
779 * Gets a value from the object.
780 *
781 * @note Needs to be destroyed using grip_destroy_json_value() native.
782 * @note If dot notation is used some values may be inaccessible
783 * because valid names in JSON can contain dots.
784 *
785 * @param object Object handle
786 * @param name Key name
787 * @param dot_not True to use dot notation, false to not
788 *
789 * @return JSON handle, Invalid_GripJSONValue if error occurred
790 * @error If passed handle is not a valid object
791 */
792 native GripJSONValue:grip_json_object_get_value(const GripJSONValue:object, const name[], bool:dot_not = false);
793
794 /**
795 * Gets string data from the object.
796 *
797 * @note If dot notation is used some values may be inaccessible
798 * because valid names in JSON can contain dots.
799 *
800 * @param object Object handle
801 * @param name Key name
802 * @param buffer Buffer to copy string to
803 * @param maxlen Maximum size of the buffer
804 * @param dot_not True to use dot notation, false to not
805 *
806 * @return The number of cells written to the buffer
807 * @error If passed handle is not a valid object
808 */
809 native grip_json_object_get_string(const GripJSONValue:object, const name[], buffer[], maxlen, bool:dot_not = false);
810
811 /**
812 * Gets a number from the object.
813 *
814 * @note If dot notation is used some values may be inaccessible
815 * because valid names in JSON can contain dots.
816 *
817 * @param object Object handle
818 * @param name Key name
819 * @param dot_not True to use dot notation, false to not
820 *
821 * @return Number
822 * @error If passed handle is not a valid object
823 */
824 native grip_json_object_get_number(const GripJSONValue:object, const name[], bool:dot_not = false);
825
826 /**
827 * Gets a real number from the object.
828 *
829 * @note If dot notation is used some values may be inaccessible
830 * because valid names in JSON can contain dots.
831 *
832 * @param object Object handle
833 * @param name Key name
834 * @param dot_not True to use dot notation, false to not
835 *
836 * @return Real number
837 * @error If passed handle is not a valid object
838 */
839 native Float:grip_json_object_get_float(const GripJSONValue:object, const name[], bool:dot_not = false);
840 #define grip_json_object_get_real(%1, %2, %3) grip_json_object_get_float(%1, %2, %3)
841
842 /**
843 * Gets a boolean value from the object.
844 *
845 * @note If dot notation is used some values may be inaccessible
846 * because valid names in JSON can contain dots.
847 *
848 * @param object Object handle
849 * @param name Key name
850 * @param dot_not True to use dot notation, false to not
851 *
852 * @return Boolean value
853 * @error If passed handle is not a valid object
854 */
855 native bool:grip_json_object_get_bool(const GripJSONValue:object, const name[], bool:dot_not = false);
856
857 /**
858 * Gets count of the keys in the object.
859 *
860 * @param object Object handle
861 *
862 * @return Keys count
863 * @error If passed handle is not a valid object
864 */
865 native grip_json_object_get_count(const GripJSONValue:object);
866
867 /**
868 * Gets name of the object's key.
869 *
870 * @param object Object handle
871 * @param index Position from which get key name
872 * @param buffer Buffer to copy string to
873 * @param maxlen Maximum size of the buffer
874 *
875 * @return The number of cells written to the buffer
876 * @error If passed handle is not a valid object
877 */
878 native grip_json_object_get_name(const GripJSONValue:object, index, buffer[], maxlen);
879
880 /**
881 * Gets a value at the specified position from the object.
882 *
883 * @note Needs to be destroyed using grip_destroy_json_value() native.
884 *
885 * @param object Object handle
886 * @param index Position from which get key name
887 *
888 * @return JSON handle, Invalid_GripJSONValue if error occurred
889 * @error If passed handle is not a valid object
890 */
891 native GripJSONValue:grip_json_object_get_value_at(const GripJSONValue:object, index);
892
893 /**
894 * Checks if the object has a value with a specific name and type.
895 *
896 * @param object Object handle
897 * @param name Key name
898 * @param type Type of value, if JSONError type will not be checked
899 * @param dot_not True to use dot notation, false to not
900 *
901 * @return True if has, false if not
902 * @error If passed handle is not a valid object
903 */
904 native bool:grip_json_object_has_value(const GripJSONValue:object, const name[], GripJSONType:type = GripJSONError, bool:dot_not = false);
905
906 /**
907 * Sets a value in the object.
908 *
909 * @note If dot notation is used some values may be inaccessible
910 * because valid names in JSON can contain dots.
911 * @note It also removes the old value if any.
912 *
913 * @param object Object handle
914 * @param name Key name
915 * @param value JSON handle to set
916 * @param dot_not True to use dot notation, false to not
917 *
918 * @return True if succeed, false otherwise
919 * @error If passed handle is not a valid object
920 */
921 native bool:grip_json_object_set_value(GripJSONValue:object, const name[], const GripJSONValue:value, bool:dot_not = false);
922
923 /**
924 * Sets string data in the object.
925 *
926 * @note If dot notation is used some values may be inaccessible
927 * because valid names in JSON can contain dots.
928 * @note It also removes the old value if any.
929 *
930 * @param object Object handle
931 * @param name Key name
932 * @param string String to copy
933 * @param dot_not True to use dot notation, false to not
934 *
935 * @return True if succeed, false otherwise
936 * @error If passed handle is not a valid object
937 */
938 native bool:grip_json_object_set_string(GripJSONValue:object, const name[], const string[], bool:dot_not = false);
939
940 /**
941 * Sets a number in the object.
942 *
943 * @note If dot notation is used some values may be inaccessible
944 * because valid names in JSON can contain dots.
945 * @note It also removes the old value if any.
946 *
947 * @param object Object handle
948 * @param name Key name
949 * @param number Number to set
950 * @param dot_not True to use dot notation, false to not
951 *
952 * @return True if succeed, false otherwise
953 * @error If passed handle is not a valid object
954 */
955 native bool:grip_json_object_set_number(GripJSONValue:object, const name[], number, bool:dot_not = false);
956
957 /**
958 * Sets a real number in the object.
959 *
960 * @note If dot notation is used some values may be inaccessible
961 * because valid names in JSON can contain dots.
962 * @note It also removes the old value if any.
963 *
964 * @param object Object handle
965 * @param name Key name
966 * @param number Real number to set
967 * @param dot_not True to use dot notation, false to not
968 *
969 * @return True if succeed, false otherwise
970 * @error If passed handle is not a valid object
971 */
972 native bool:grip_json_object_set_float(GripJSONValue:object, const name[], Float:number, bool:dot_not = false);
973 #define grip_json_object_set_real(%1, %2, %3, %4) grip_json_object_set_float(%1, %2, %3, %4)
974
975 /**
976 * Sets a boolean value in the object.
977 *
978 * @note If dot notation is used some values may be inaccessible
979 * because valid names in JSON can contain dots.
980 * @note It also removes the old value if any.
981 *
982 * @param object Object handle
983 * @param name Key name
984 * @param boolean Boolean value to set
985 * @param dot_not True to use dot notation, false to not
986 *
987 * @return True if succeed, false otherwise
988 * @error If passed handle is not a valid object
989 */
990 native bool:grip_json_object_set_bool(GripJSONValue:object, const name[], bool:boolean, bool:dot_not = false);
991
992 /**
993 * Sets a null in the object.
994 *
995 * @note If dot notation is used some values may be inaccessible
996 * because valid names in JSON can contain dots.
997 * @note It also removes the old value if any.
998 *
999 * @param object Object handle
1000 * @param name Key name
1001 * @param dot_not True to use dot notation, false to not
1002 *
1003 * @return True if succeed, false otherwise
1004 * @error If passed handle is not a valid object
1005 */
1006 native bool:grip_json_object_set_null(GripJSONValue:object, const name[], bool:dot_not = false);
1007
1008 /**
1009 * Removes a key and its value in the object.
1010 *
1011 * @note If dot notation is used some values may be inaccessible
1012 * because valid names in JSON can contain dots.
1013 *
1014 * @param object Object handle
1015 * @param name Key name
1016 * @param dot_not True to use dot notation, false to not
1017 *
1018 * @return True if succeed, false otherwise
1019 * @error If passed handle is not a valid object
1020 */
1021 native bool:grip_json_object_remove(GripJSONValue:object, const name[], bool:dot_not = false);
1022
1023 /**
1024 * Removes all keys and their values in the object.
1025 *
1026 * @param object Object handle
1027 *
1028 * @return True if succeed, false otherwise
1029 * @error If passed handle is not a valid object
1030 */
1031 native bool:grip_json_object_clear(GripJSONValue:object);
1032
1033 /**
1034 * Gets size of serialization.
1035 *
1036 * @param value JSON handle
1037 * @param pretty True to count size for pretty format, false to not
1038 * @param null_byte True to include null byte, false to not
1039 * @param recursion_limit Limit of the internal recursion
1040 *
1041 * @return Size of serialized string
1042 * @error If passed handle is not a valid value
1043 */
1044 native grip_json_serial_size(const GripJSONValue:value, bool:pretty = false, bool:null_byte = false, recursion_limit = 100);
1045
1046 /**
1047 * Copies serialized string to the buffer.
1048 *
1049 * @param value JSON handle
1050 * @param buffer Buffer to copy string to
1051 * @param maxlen Maximum size of the buffer
1052 * @param pretty True to format pretty JSON string, false to not
1053 * @param recursion_limit Limit of the internal recursion
1054 *
1055 * @return The number of cells written to the buffer
1056 * @error If passed handle is not a valid value
1057 */
1058 native grip_json_serial_to_string(const GripJSONValue:value, buffer[], maxlen, bool:pretty = false, recursion_limit = 100);
1059
1060 /**
1061 * Copies serialized string to the file.
1062 *
1063 * @param value JSON handle
1064 * @param file Path to the file
1065 * @param pretty True to format pretty JSON string, false to not
1066 * @param recursion_limit Limit of the internal recursion
1067 *
1068 * @return True if succeed, false otherwise
1069 * @error If passed handle is not a valid value
1070 */
1071 native bool:grip_json_serial_to_file(const GripJSONValue:value, const file[], bool:pretty = false, recursion_limit = 100);
1072