OLD | NEW |
| (Empty) |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 #ifndef DART_ARCHIVE_MESSAGING_H_ | |
6 #define DART_ARCHIVE_MESSAGING_H_ | |
7 | |
8 #include "dart_archive.h" | |
9 | |
10 /** | |
11 * Posts a reponse to the main Dart isolate. Only one response should be sent | |
12 * for each request. | |
13 * | |
14 * [p] is the reply port for the isolate. [success] indicates whether or not the | |
15 * request completed successfully; if not, [err] indicates the precise nature of | |
16 * the error. [response] contains request-specific response data to send to | |
17 * Dart; it may not be `NULL`, but it may be the Dart `null` value. | |
18 */ | |
19 void postResult(Dart_Port p, bool success, int err, Dart_CObject* response); | |
20 | |
21 /** | |
22 * Posts an error response to the main Dart isolate. | |
23 * | |
24 * This should be used when libarchive signals an error. The errno and error | |
25 * message are taken from libarchive's built-in error information for [a]. | |
26 */ | |
27 void postError(Dart_Port p, struct archive* a); | |
28 | |
29 /** | |
30 * Posts an invalid argument error response to the main Dart isolate. | |
31 * | |
32 * This should be used when the arguments sent by the Dart code have unexpected | |
33 * types. Takes a `printf`-style [format] string for describing the error. Note | |
34 * that the error string will be cut off at 256 characters. | |
35 */ | |
36 void postInvalidArgument(Dart_Port p, const char* format, ...); | |
37 | |
38 /** | |
39 * Posts a success response to the main Dart isolate. [response] is the | |
40 * request-specific Dart object containing the response data. It may be `NULL`. | |
41 */ | |
42 void postSuccess(Dart_Port p, Dart_CObject* response); | |
43 | |
44 /** | |
45 * Checks [error], the return code of a libarchive call for error conditions, | |
46 * and sends an appropriate error response if any are detected. | |
47 * | |
48 * Returns `true` if an error is detected and the containing function should | |
49 * short-circuit. | |
50 */ | |
51 bool checkError(Dart_Port p, struct archive* a, int result); | |
52 | |
53 /** | |
54 * Sends an error response if [pointer] is invalid. [name] is the name of the | |
55 * object being allocated, for error reporting. | |
56 * | |
57 * Returns `true` if an error is detected and the containing function should | |
58 * short-circuit. | |
59 */ | |
60 bool checkPointerError(Dart_Port p, void* pointer, char* name); | |
61 | |
62 /** | |
63 * Like [checkError], but sends a success message with no attached data if no | |
64 * error is detected. No further responses should be sent after calling this. | |
65 */ | |
66 void checkResult(Dart_Port p, struct archive* a, int result); | |
67 | |
68 /** | |
69 * Like [checkPointerError], but sends a success message with the pointer as a | |
70 * Dart integer if no error is detected. No further responses should be sent | |
71 * after calling this. | |
72 */ | |
73 void checkPointerResult(Dart_Port p, void* pointer, char* name); | |
74 | |
75 /** | |
76 * Checks that [object] is of the expected type [type]. If not, sends an | |
77 * appropriate error response. | |
78 * | |
79 * Returns `true` if a type error is detected and the containing function should | |
80 * short-circuit. | |
81 */ | |
82 bool checkType(Dart_Port p, Dart_CObject* object, enum Type type); | |
83 | |
84 /** | |
85 * Gets the [i]th argument from [request], which should be the Dart object | |
86 * passed in to each handler function. If this fails (e.g. there isn't an [i]th | |
87 * argument), it will return `NULL`. | |
88 */ | |
89 Dart_CObject* getArgument(Dart_Port p, Dart_CObject* request, int i); | |
90 | |
91 /** | |
92 * Like [getArgument], but also ensures that the argument is of type [type]. | |
93 */ | |
94 Dart_CObject* getTypedArgument(Dart_Port p, Dart_CObject* request, int i, | |
95 enum Type type); | |
96 | |
97 /** | |
98 * Like [getArgument], but also ensures that the argument is an integer type | |
99 * (`int32` or `int64`). [getInteger] should be used to extract the actual value | |
100 * of the argument. | |
101 */ | |
102 Dart_CObject* getIntArgument(Dart_Port p, Dart_CObject* request, int i); | |
103 | |
104 /** | |
105 * Gets the integer value of [object], which should be an `int32` or an `int64`. | |
106 * Note that this does not validate the type of its argument. | |
107 */ | |
108 int64_t getInteger(Dart_CObject* object); | |
109 | |
110 /** | |
111 * Like [getArgument], but also ensures that the argument is a string or null. | |
112 * [getNullableString] should be used to extract the actual value of the | |
113 * argument. | |
114 */ | |
115 Dart_CObject* getNullableStringArgument(Dart_Port p, Dart_CObject* request, | |
116 int i); | |
117 | |
118 /** | |
119 * Gets the string value of [object] or `NULL` if it's null. Note that this does | |
120 * not validate the type of its argument. | |
121 */ | |
122 char* getNullableString(Dart_CObject* object); | |
123 | |
124 /** | |
125 * Gets the module, name, and value, for a libarchive `set_option` function | |
126 * call. Returns whether or not the arguments were parsed correctly. | |
127 */ | |
128 bool getOptionArguments(Dart_Port p, Dart_CObject* request, char** module, | |
129 char** name, char** value); | |
130 | |
131 /** Declares a null [Dart_CObject] named [name]. */ | |
132 #define DART_NULL(name) \ | |
133 Dart_CObject name; \ | |
134 name.type = kNull; | |
135 | |
136 /** | |
137 * Declares a [Dart_CObject] bool named [name] with value [val]. | |
138 * | |
139 * [val] should be a C boolean. | |
140 */ | |
141 #define DART_BOOL(name, val) \ | |
142 Dart_CObject name; \ | |
143 name.type = kBool; \ | |
144 name.value.as_bool = val; | |
145 | |
146 /** | |
147 * Declares a [Dart_CObject] `int32` named [name] with value [val]. | |
148 * | |
149 * [val] should be a C integer. | |
150 */ | |
151 #define DART_INT32(name, val) \ | |
152 Dart_CObject name; \ | |
153 name.type = kInt32; \ | |
154 name.value.as_int32 = val; | |
155 | |
156 /** | |
157 * Declares a [Dart_CObject] `int64` named [name] with value [val]. | |
158 * | |
159 * [val] should be a C integer. | |
160 */ | |
161 #define DART_INT64(name, val) \ | |
162 Dart_CObject name; \ | |
163 name.type = kInt64; \ | |
164 name.value.as_int64 = val; | |
165 | |
166 /** | |
167 * Declares a [Dart_CObject] double named [name] with value [val]. | |
168 * | |
169 * [val] should be a C float. | |
170 */ | |
171 #define DART_DOUBLE(name, val) \ | |
172 Dart_CObject name; \ | |
173 name.type = kDouble; \ | |
174 name.value.as_double = val; | |
175 | |
176 /** | |
177 * Declares a [Dart_CObject] string named [name] with value [val]. | |
178 * | |
179 * [val] should be a C string or `NULL`. | |
180 */ | |
181 #define DART_STRING(name, val) \ | |
182 Dart_CObject name; \ | |
183 if (val == NULL) { \ | |
184 name.type = kNull; \ | |
185 } else { \ | |
186 name.type = kString; \ | |
187 name.value.as_string = val; \ | |
188 } | |
189 | |
190 #endif // DART_ARCHIVE_MESSAGING_H_ | |
OLD | NEW |