|
| 1 | +/* |
| 2 | + * |
| 3 | + * Copyright 2016, Google Inc. |
| 4 | + * All rights reserved. |
| 5 | + * |
| 6 | + * Redistribution and use in source and binary forms, with or without |
| 7 | + * modification, are permitted provided that the following conditions are |
| 8 | + * met: |
| 9 | + * |
| 10 | + * * Redistributions of source code must retain the above copyright |
| 11 | + * notice, this list of conditions and the following disclaimer. |
| 12 | + * * Redistributions in binary form must reproduce the above |
| 13 | + * copyright notice, this list of conditions and the following disclaimer |
| 14 | + * in the documentation and/or other materials provided with the |
| 15 | + * distribution. |
| 16 | + * * Neither the name of Google Inc. nor the names of its |
| 17 | + * contributors may be used to endorse or promote products derived from |
| 18 | + * this software without specific prior written permission. |
| 19 | + * |
| 20 | + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 21 | + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 22 | + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 23 | + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 24 | + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 25 | + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 26 | + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 27 | + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 28 | + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 29 | + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 30 | + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 31 | + * |
| 32 | + */ |
| 33 | +#ifndef cgrpc_h |
| 34 | +#define cgrpc_h |
| 35 | + |
| 36 | +#import <stdlib.h> |
| 37 | + |
| 38 | +// This file lists C functions and types used to build Swift gRPC support |
| 39 | + |
| 40 | +#ifndef cgrpc_internal_h |
| 41 | +// all domain types are opaque pointers |
| 42 | +typedef void cgrpc_byte_buffer; |
| 43 | +typedef void cgrpc_call; |
| 44 | +typedef void cgrpc_channel; |
| 45 | +typedef void cgrpc_completion_queue; |
| 46 | +typedef void cgrpc_handler; |
| 47 | +typedef void cgrpc_metadata; |
| 48 | +typedef void cgrpc_metadata_array; |
| 49 | +typedef void cgrpc_mutex; |
| 50 | +typedef void cgrpc_observer; |
| 51 | +typedef void cgrpc_observer_send_initial_metadata; |
| 52 | +typedef void cgrpc_observer_send_message; |
| 53 | +typedef void cgrpc_observer_send_close_from_client; |
| 54 | +typedef void cgrpc_observer_send_status_from_server; |
| 55 | +typedef void cgrpc_observer_recv_initial_metadata; |
| 56 | +typedef void cgrpc_observer_recv_message; |
| 57 | +typedef void cgrpc_observer_recv_status_on_client; |
| 58 | +typedef void cgrpc_observer_recv_close_on_server; |
| 59 | +typedef void cgrpc_operations; |
| 60 | +typedef void cgrpc_server; |
| 61 | + |
| 62 | +/** Result of a grpc call. If the caller satisfies the prerequisites of a |
| 63 | + particular operation, the grpc_call_error returned will be GRPC_CALL_OK. |
| 64 | + Receiving any other value listed here is an indication of a bug in the |
| 65 | + caller. */ |
| 66 | +typedef enum grpc_call_error { |
| 67 | + /** everything went ok */ |
| 68 | + GRPC_CALL_OK = 0, |
| 69 | + /** something failed, we don't know what */ |
| 70 | + GRPC_CALL_ERROR, |
| 71 | + /** this method is not available on the server */ |
| 72 | + GRPC_CALL_ERROR_NOT_ON_SERVER, |
| 73 | + /** this method is not available on the client */ |
| 74 | + GRPC_CALL_ERROR_NOT_ON_CLIENT, |
| 75 | + /** this method must be called before server_accept */ |
| 76 | + GRPC_CALL_ERROR_ALREADY_ACCEPTED, |
| 77 | + /** this method must be called before invoke */ |
| 78 | + GRPC_CALL_ERROR_ALREADY_INVOKED, |
| 79 | + /** this method must be called after invoke */ |
| 80 | + GRPC_CALL_ERROR_NOT_INVOKED, |
| 81 | + /** this call is already finished |
| 82 | + (writes_done or write_status has already been called) */ |
| 83 | + GRPC_CALL_ERROR_ALREADY_FINISHED, |
| 84 | + /** there is already an outstanding read/write operation on the call */ |
| 85 | + GRPC_CALL_ERROR_TOO_MANY_OPERATIONS, |
| 86 | + /** the flags value was illegal for this call */ |
| 87 | + GRPC_CALL_ERROR_INVALID_FLAGS, |
| 88 | + /** invalid metadata was passed to this call */ |
| 89 | + GRPC_CALL_ERROR_INVALID_METADATA, |
| 90 | + /** invalid message was passed to this call */ |
| 91 | + GRPC_CALL_ERROR_INVALID_MESSAGE, |
| 92 | + /** completion queue for notification has not been registered with the |
| 93 | + server */ |
| 94 | + GRPC_CALL_ERROR_NOT_SERVER_COMPLETION_QUEUE, |
| 95 | + /** this batch of operations leads to more operations than allowed */ |
| 96 | + GRPC_CALL_ERROR_BATCH_TOO_BIG, |
| 97 | + /** payload type requested is not the type registered */ |
| 98 | + GRPC_CALL_ERROR_PAYLOAD_TYPE_MISMATCH |
| 99 | +} grpc_call_error; |
| 100 | + |
| 101 | +/** The type of completion (for grpc_event) */ |
| 102 | +typedef enum grpc_completion_type { |
| 103 | + /** Shutting down */ |
| 104 | + GRPC_QUEUE_SHUTDOWN, |
| 105 | + /** No event before timeout */ |
| 106 | + GRPC_QUEUE_TIMEOUT, |
| 107 | + /** Operation completion */ |
| 108 | + GRPC_OP_COMPLETE |
| 109 | +} grpc_completion_type; |
| 110 | + |
| 111 | +typedef struct grpc_event { |
| 112 | + /** The type of the completion. */ |
| 113 | + grpc_completion_type type; |
| 114 | + /** non-zero if the operation was successful, 0 upon failure. |
| 115 | + Only GRPC_OP_COMPLETE can succeed or fail. */ |
| 116 | + int success; |
| 117 | + /** The tag passed to grpc_call_start_batch etc to start this operation. |
| 118 | + Only GRPC_OP_COMPLETE has a tag. */ |
| 119 | + void *tag; |
| 120 | +} grpc_event; |
| 121 | + |
| 122 | +#endif |
| 123 | + |
| 124 | +// directly expose a few grpc library functions |
| 125 | +void grpc_init(); |
| 126 | +void grpc_shutdown(); |
| 127 | +const char *grpc_version_string(); |
| 128 | + |
| 129 | +// channel support |
| 130 | +cgrpc_channel *cgrpc_channel_create(const char *address); |
| 131 | +cgrpc_channel *cgrpc_channel_create_secure(const char *address, |
| 132 | + const char *pem_root_certs, |
| 133 | + const char *host); |
| 134 | + |
| 135 | +void cgrpc_channel_destroy(cgrpc_channel *channel); |
| 136 | +cgrpc_call *cgrpc_channel_create_call(cgrpc_channel *channel, |
| 137 | + const char *method, |
| 138 | + const char *host, |
| 139 | + double timeout); |
| 140 | +cgrpc_completion_queue *cgrpc_channel_completion_queue(cgrpc_channel *channel); |
| 141 | + |
| 142 | +// server support |
| 143 | +cgrpc_server *cgrpc_server_create(const char *address); |
| 144 | +cgrpc_server *cgrpc_server_create_secure(const char *address, |
| 145 | + const char *private_key, |
| 146 | + const char *cert_chain); |
| 147 | +void cgrpc_server_stop(cgrpc_server *server); |
| 148 | +void cgrpc_server_destroy(cgrpc_server *s); |
| 149 | +void cgrpc_server_start(cgrpc_server *s); |
| 150 | +cgrpc_completion_queue *cgrpc_server_get_completion_queue(cgrpc_server *s); |
| 151 | + |
| 152 | +// completion queues |
| 153 | +grpc_event cgrpc_completion_queue_get_next_event(cgrpc_completion_queue *cq, |
| 154 | + double timeout); |
| 155 | +void cgrpc_completion_queue_drain(cgrpc_completion_queue *cq); |
| 156 | +void cgrpc_completion_queue_shutdown(cgrpc_completion_queue *cq); |
| 157 | + |
| 158 | +// server request handlers |
| 159 | +cgrpc_handler *cgrpc_handler_create_with_server(cgrpc_server *server); |
| 160 | +void cgrpc_handler_destroy(cgrpc_handler *h); |
| 161 | +cgrpc_call *cgrpc_handler_get_call(cgrpc_handler *h); |
| 162 | +cgrpc_completion_queue *cgrpc_handler_get_completion_queue(cgrpc_handler *h); |
| 163 | + |
| 164 | +grpc_call_error cgrpc_handler_request_call(cgrpc_handler *h, |
| 165 | + cgrpc_metadata_array *metadata, |
| 166 | + long tag); |
| 167 | +const char *cgrpc_handler_host(cgrpc_handler *h); |
| 168 | +const char *cgrpc_handler_method(cgrpc_handler *h); |
| 169 | +const char *cgrpc_handler_call_peer(cgrpc_handler *h); |
| 170 | + |
| 171 | +// call support |
| 172 | +void cgrpc_call_destroy(cgrpc_call *call); |
| 173 | +grpc_call_error cgrpc_call_perform(cgrpc_call *call, cgrpc_operations *operations, int64_t tag); |
| 174 | + |
| 175 | +// operations |
| 176 | +cgrpc_operations *cgrpc_operations_create(); |
| 177 | +void cgrpc_operations_destroy(cgrpc_operations *operations); |
| 178 | +void cgrpc_operations_reserve_space_for_operations(cgrpc_operations *call, int max_operations); |
| 179 | +void cgrpc_operations_add_operation(cgrpc_operations *call, cgrpc_observer *observer); |
| 180 | + |
| 181 | +// metadata support |
| 182 | +cgrpc_metadata_array *cgrpc_metadata_array_create(); |
| 183 | +void cgrpc_metadata_array_destroy(cgrpc_metadata_array *array); |
| 184 | +size_t cgrpc_metadata_array_get_count(cgrpc_metadata_array *array); |
| 185 | +const char *cgrpc_metadata_array_get_key_at_index(cgrpc_metadata_array *array, size_t index); |
| 186 | +const char *cgrpc_metadata_array_get_value_at_index(cgrpc_metadata_array *array, size_t index); |
| 187 | +void cgrpc_metadata_array_move_metadata(cgrpc_metadata_array *dest, cgrpc_metadata_array *src); |
| 188 | +void cgrpc_metadata_array_append_metadata(cgrpc_metadata_array *metadata, const char *key, const char *value); |
| 189 | + |
| 190 | +// mutex support |
| 191 | +cgrpc_mutex *cgrpc_mutex_create(); |
| 192 | +void cgrpc_mutex_destroy(cgrpc_mutex *mu); |
| 193 | +void cgrpc_mutex_lock(cgrpc_mutex *mu); |
| 194 | +void cgrpc_mutex_unlock(cgrpc_mutex *mu); |
| 195 | + |
| 196 | +// byte buffer support |
| 197 | +void cgrpc_byte_buffer_destroy(cgrpc_byte_buffer *bb); |
| 198 | +cgrpc_byte_buffer *cgrpc_byte_buffer_create_by_copying_data(const void *source, size_t len); |
| 199 | +const void *cgrpc_byte_buffer_copy_data(cgrpc_byte_buffer *bb, size_t *length); |
| 200 | + |
| 201 | +// event support |
| 202 | +int64_t cgrpc_event_tag(grpc_event ev); |
| 203 | + |
| 204 | +// observers |
| 205 | + |
| 206 | +// constructors |
| 207 | +cgrpc_observer_send_initial_metadata *cgrpc_observer_create_send_initial_metadata(cgrpc_metadata_array *metadata); |
| 208 | +cgrpc_observer_send_message *cgrpc_observer_create_send_message(); |
| 209 | +cgrpc_observer_send_close_from_client *cgrpc_observer_create_send_close_from_client(); |
| 210 | +cgrpc_observer_send_status_from_server *cgrpc_observer_create_send_status_from_server(cgrpc_metadata_array *metadata); |
| 211 | +cgrpc_observer_recv_initial_metadata *cgrpc_observer_create_recv_initial_metadata(); |
| 212 | +cgrpc_observer_recv_message *cgrpc_observer_create_recv_message(); |
| 213 | +cgrpc_observer_recv_status_on_client *cgrpc_observer_create_recv_status_on_client(); |
| 214 | +cgrpc_observer_recv_close_on_server *cgrpc_observer_create_recv_close_on_server(); |
| 215 | + |
| 216 | +// destructor |
| 217 | +void cgrpc_observer_destroy(cgrpc_observer *observer); |
| 218 | + |
| 219 | +// GRPC_OP_SEND_INITIAL_METADATA |
| 220 | + |
| 221 | + |
| 222 | +// GRPC_OP_SEND_MESSAGE |
| 223 | +void cgrpc_observer_send_message_set_message(cgrpc_observer_send_message *observer, |
| 224 | + cgrpc_byte_buffer *message); |
| 225 | + |
| 226 | +// GRPC_OP_SEND_CLOSE_FROM_CLIENT |
| 227 | +// -- no special handlers -- |
| 228 | + |
| 229 | +// GRPC_OP_SEND_STATUS_FROM_SERVER |
| 230 | +void cgrpc_observer_send_status_from_server_set_status |
| 231 | +(cgrpc_observer_send_status_from_server *observer, |
| 232 | + int status); |
| 233 | + |
| 234 | +void cgrpc_observer_send_status_from_server_set_status_details |
| 235 | +(cgrpc_observer_send_status_from_server *observer, |
| 236 | + const char *statusDetails); |
| 237 | + |
| 238 | +// GRPC_OP_RECV_INITIAL_METADATA |
| 239 | +cgrpc_metadata_array *cgrpc_observer_recv_initial_metadata_get_metadata |
| 240 | +(cgrpc_observer_recv_initial_metadata *observer); |
| 241 | + |
| 242 | +// GRPC_OP_RECV_MESSAGE |
| 243 | +cgrpc_byte_buffer *cgrpc_observer_recv_message_get_message |
| 244 | +(cgrpc_observer_recv_message *observer); |
| 245 | + |
| 246 | +// GRPC_OP_RECV_STATUS_ON_CLIENT |
| 247 | +cgrpc_metadata_array *cgrpc_observer_recv_status_on_client_get_metadata |
| 248 | +(cgrpc_observer_recv_status_on_client *observer); |
| 249 | + |
| 250 | +long cgrpc_observer_recv_status_on_client_get_status |
| 251 | +(cgrpc_observer_recv_status_on_client *observer); |
| 252 | + |
| 253 | +const char *cgrpc_observer_recv_status_on_client_get_status_details |
| 254 | +(cgrpc_observer_recv_status_on_client *observer); |
| 255 | + |
| 256 | +// GRPC_OP_RECV_CLOSE_ON_SERVER |
| 257 | +int cgrpc_observer_recv_close_on_server_was_cancelled |
| 258 | +(cgrpc_observer_recv_close_on_server *observer); |
| 259 | + |
| 260 | +#endif |
0 commit comments