Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 1 | /* |
| 2 | * |
Craig Tiller | 6169d5f | 2016-03-31 07:46:18 -0700 | [diff] [blame] | 3 | * Copyright 2015, Google Inc. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 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 | |
Nicolas "Pixel" Noble | 1ff52d5 | 2015-03-01 05:24:36 +0100 | [diff] [blame] | 34 | #ifndef GRPC_GRPC_H |
| 35 | #define GRPC_GRPC_H |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 36 | |
| 37 | #include <grpc/status.h> |
| 38 | |
David Garcia Quintas | 25d02d5 | 2015-06-04 17:40:54 -0700 | [diff] [blame] | 39 | #include <grpc/byte_buffer.h> |
Craig Tiller | f40df23 | 2016-03-25 13:38:14 -0700 | [diff] [blame] | 40 | #include <grpc/impl/codegen/connectivity_state.h> |
| 41 | #include <grpc/impl/codegen/grpc_types.h> |
| 42 | #include <grpc/impl/codegen/propagation_bits.h> |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 43 | #include <grpc/support/slice.h> |
| 44 | #include <grpc/support/time.h> |
Craig Tiller | f40df23 | 2016-03-25 13:38:14 -0700 | [diff] [blame] | 45 | #include <stddef.h> |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 46 | |
| 47 | #ifdef __cplusplus |
| 48 | extern "C" { |
| 49 | #endif |
| 50 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 51 | /*! \mainpage GRPC Core |
| 52 | * |
Craig Tiller | d6599a3 | 2015-09-03 09:37:02 -0700 | [diff] [blame] | 53 | * The GRPC Core library is a low-level library designed to be wrapped by higher |
| 54 | * level libraries. The top-level API is provided in grpc.h. Security related |
| 55 | * functionality lives in grpc_security.h. |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 56 | */ |
| 57 | |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 58 | GRPCAPI void grpc_metadata_array_init(grpc_metadata_array *array); |
| 59 | GRPCAPI void grpc_metadata_array_destroy(grpc_metadata_array *array); |
Craig Tiller | ea61b07 | 2015-02-03 19:19:27 -0800 | [diff] [blame] | 60 | |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 61 | GRPCAPI void grpc_call_details_init(grpc_call_details *details); |
| 62 | GRPCAPI void grpc_call_details_destroy(grpc_call_details *details); |
Craig Tiller | ea61b07 | 2015-02-03 19:19:27 -0800 | [diff] [blame] | 63 | |
Hongwei Wang | 85ad685 | 2015-08-13 16:13:10 -0700 | [diff] [blame] | 64 | /** Registers a plugin to be initialized and destroyed with the library. |
Hongwei Wang | a83d1b3 | 2015-08-06 12:52:18 -0700 | [diff] [blame] | 65 | |
Craig Tiller | d6c98df | 2015-08-18 09:33:44 -0700 | [diff] [blame] | 66 | The \a init and \a destroy functions will be invoked as part of |
| 67 | \a grpc_init() and \a grpc_shutdown(), respectively. |
Hongwei Wang | 85ad685 | 2015-08-13 16:13:10 -0700 | [diff] [blame] | 68 | Note that these functions can be invoked an arbitrary number of times |
| 69 | (and hence so will \a init and \a destroy). |
Craig Tiller | d6c98df | 2015-08-18 09:33:44 -0700 | [diff] [blame] | 70 | It is safe to pass NULL to either argument. Plugins are destroyed in |
Hongwei Wang | 85ad685 | 2015-08-13 16:13:10 -0700 | [diff] [blame] | 71 | the reverse order they were initialized. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 72 | GRPCAPI void grpc_register_plugin(void (*init)(void), void (*destroy)(void)); |
Hongwei Wang | a3780a8 | 2015-07-17 15:27:18 -0700 | [diff] [blame] | 73 | |
Craig Tiller | e793ba1 | 2015-05-18 09:37:22 -0700 | [diff] [blame] | 74 | /** Initialize the grpc library. |
Craig Tiller | 8674cb1 | 2015-06-05 07:09:25 -0700 | [diff] [blame] | 75 | |
Craig Tiller | e793ba1 | 2015-05-18 09:37:22 -0700 | [diff] [blame] | 76 | It is not safe to call any other grpc functions before calling this. |
| 77 | (To avoid overhead, little checking is done, and some things may work. We |
| 78 | do not warrant that they will continue to do so in future revisions of this |
| 79 | library). */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 80 | GRPCAPI void grpc_init(void); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 81 | |
Craig Tiller | e793ba1 | 2015-05-18 09:37:22 -0700 | [diff] [blame] | 82 | /** Shut down the grpc library. |
Craig Tiller | 8674cb1 | 2015-06-05 07:09:25 -0700 | [diff] [blame] | 83 | |
Craig Tiller | e793ba1 | 2015-05-18 09:37:22 -0700 | [diff] [blame] | 84 | No memory is used by grpc after this call returns, nor are any instructions |
| 85 | executing within the grpc library. |
| 86 | Prior to calling, all application owned grpc objects must have been |
| 87 | destroyed. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 88 | GRPCAPI void grpc_shutdown(void); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 89 | |
Craig Tiller | 2e622bc | 2015-07-10 07:46:03 -0700 | [diff] [blame] | 90 | /** Return a string representing the current version of grpc */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 91 | GRPCAPI const char *grpc_version_string(void); |
Craig Tiller | 2e622bc | 2015-07-10 07:46:03 -0700 | [diff] [blame] | 92 | |
Craig Tiller | e793ba1 | 2015-05-18 09:37:22 -0700 | [diff] [blame] | 93 | /** Create a completion queue */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 94 | GRPCAPI grpc_completion_queue *grpc_completion_queue_create(void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 95 | |
Craig Tiller | e793ba1 | 2015-05-18 09:37:22 -0700 | [diff] [blame] | 96 | /** Blocks until an event is available, the completion queue is being shut down, |
Craig Tiller | 8674cb1 | 2015-06-05 07:09:25 -0700 | [diff] [blame] | 97 | or deadline is reached. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 98 | |
vjpai | 1854d77 | 2015-06-08 01:12:29 -0700 | [diff] [blame] | 99 | Returns a grpc_event with type GRPC_QUEUE_TIMEOUT on timeout, |
| 100 | otherwise a grpc_event describing the event that occurred. |
Craig Tiller | e793ba1 | 2015-05-18 09:37:22 -0700 | [diff] [blame] | 101 | |
| 102 | Callers must not call grpc_completion_queue_next and |
| 103 | grpc_completion_queue_pluck simultaneously on the same completion queue. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 104 | GRPCAPI grpc_event grpc_completion_queue_next(grpc_completion_queue *cq, |
| 105 | gpr_timespec deadline, |
| 106 | void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 107 | |
Craig Tiller | e793ba1 | 2015-05-18 09:37:22 -0700 | [diff] [blame] | 108 | /** Blocks until an event with tag 'tag' is available, the completion queue is |
Craig Tiller | 8674cb1 | 2015-06-05 07:09:25 -0700 | [diff] [blame] | 109 | being shutdown or deadline is reached. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 110 | |
vjpai | 1854d77 | 2015-06-08 01:12:29 -0700 | [diff] [blame] | 111 | Returns a grpc_event with type GRPC_QUEUE_TIMEOUT on timeout, |
| 112 | otherwise a grpc_event describing the event that occurred. |
Craig Tiller | e793ba1 | 2015-05-18 09:37:22 -0700 | [diff] [blame] | 113 | |
| 114 | Callers must not call grpc_completion_queue_next and |
Hongwei Wang | 85ad685 | 2015-08-13 16:13:10 -0700 | [diff] [blame] | 115 | grpc_completion_queue_pluck simultaneously on the same completion queue. |
| 116 | |
Craig Tiller | 489df07 | 2015-08-01 16:15:45 -0700 | [diff] [blame] | 117 | Completion queues support a maximum of GRPC_MAX_COMPLETION_QUEUE_PLUCKERS |
| 118 | concurrently executing plucks at any time. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 119 | GRPCAPI grpc_event grpc_completion_queue_pluck(grpc_completion_queue *cq, |
| 120 | void *tag, gpr_timespec deadline, |
| 121 | void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 122 | |
Craig Tiller | 489df07 | 2015-08-01 16:15:45 -0700 | [diff] [blame] | 123 | /** Maximum number of outstanding grpc_completion_queue_pluck executions per |
| 124 | completion queue */ |
| 125 | #define GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 6 |
| 126 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 127 | /** Begin destruction of a completion queue. Once all possible events are |
| 128 | drained then grpc_completion_queue_next will start to produce |
| 129 | GRPC_QUEUE_SHUTDOWN events only. At that point it's safe to call |
| 130 | grpc_completion_queue_destroy. |
Craig Tiller | b20111c | 2015-04-10 23:27:11 +0000 | [diff] [blame] | 131 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 132 | After calling this function applications should ensure that no |
| 133 | NEW work is added to be published on this completion queue. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 134 | GRPCAPI void grpc_completion_queue_shutdown(grpc_completion_queue *cq); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 135 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 136 | /** Destroy a completion queue. The caller must ensure that the queue is |
| 137 | drained and no threads are executing grpc_completion_queue_next */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 138 | GRPCAPI void grpc_completion_queue_destroy(grpc_completion_queue *cq); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 139 | |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 140 | /** Create a completion queue alarm instance associated to \a cq. |
| 141 | * |
David Garcia Quintas | 7fd0fd5 | 2015-10-07 17:41:08 -0700 | [diff] [blame] | 142 | * Once the alarm expires (at \a deadline) or it's cancelled (see \a |
| 143 | * grpc_alarm_cancel), an event with tag \a tag will be added to \a cq. If the |
| 144 | * alarm expired, the event's success bit will be true, false otherwise (ie, |
| 145 | * upon cancellation). */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 146 | GRPCAPI grpc_alarm *grpc_alarm_create(grpc_completion_queue *cq, |
| 147 | gpr_timespec deadline, void *tag); |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 148 | |
David Garcia Quintas | 7fd0fd5 | 2015-10-07 17:41:08 -0700 | [diff] [blame] | 149 | /** Cancel a completion queue alarm. Calling this function over an alarm that |
| 150 | * has already fired has no effect. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 151 | GRPCAPI void grpc_alarm_cancel(grpc_alarm *alarm); |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 152 | |
| 153 | /** Destroy the given completion queue alarm, cancelling it in the process. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 154 | GRPCAPI void grpc_alarm_destroy(grpc_alarm *alarm); |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 155 | |
Craig Tiller | 48cb07c | 2015-07-15 16:16:15 -0700 | [diff] [blame] | 156 | /** Check the connectivity state of a channel. */ |
Craig Tiller | f40df23 | 2016-03-25 13:38:14 -0700 | [diff] [blame] | 157 | GRPCAPI grpc_connectivity_state grpc_channel_check_connectivity_state( |
| 158 | grpc_channel *channel, int try_to_connect); |
Craig Tiller | 48cb07c | 2015-07-15 16:16:15 -0700 | [diff] [blame] | 159 | |
| 160 | /** Watch for a change in connectivity state. |
| 161 | Once the channel connectivity state is different from last_observed_state, |
| 162 | tag will be enqueued on cq with success=1. |
| 163 | If deadline expires BEFORE the state is changed, tag will be enqueued on cq |
Craig Tiller | 2cd9dd9 | 2015-07-31 16:34:37 -0700 | [diff] [blame] | 164 | with success=0. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 165 | GRPCAPI void grpc_channel_watch_connectivity_state( |
Craig Tiller | 48cb07c | 2015-07-15 16:16:15 -0700 | [diff] [blame] | 166 | grpc_channel *channel, grpc_connectivity_state last_observed_state, |
Craig Tiller | 2cd9dd9 | 2015-07-31 16:34:37 -0700 | [diff] [blame] | 167 | gpr_timespec deadline, grpc_completion_queue *cq, void *tag); |
Craig Tiller | 48cb07c | 2015-07-15 16:16:15 -0700 | [diff] [blame] | 168 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 169 | /** Create a call given a grpc_channel, in order to call 'method'. All |
| 170 | completions are sent to 'completion_queue'. 'method' and 'host' need only |
Craig Tiller | 5847177 | 2015-07-31 17:12:34 -0700 | [diff] [blame] | 171 | live through the invocation of this function. |
| 172 | If parent_call is non-NULL, it must be a server-side call. It will be used |
Hongwei Wang | 85ad685 | 2015-08-13 16:13:10 -0700 | [diff] [blame] | 173 | to propagate properties from the server call to this new client call. |
Craig Tiller | 5847177 | 2015-07-31 17:12:34 -0700 | [diff] [blame] | 174 | */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 175 | GRPCAPI grpc_call *grpc_channel_create_call( |
Craig Tiller | d6546c9 | 2016-01-29 07:59:35 -0800 | [diff] [blame] | 176 | grpc_channel *channel, grpc_call *parent_call, uint32_t propagation_mask, |
| 177 | grpc_completion_queue *completion_queue, const char *method, |
| 178 | const char *host, gpr_timespec deadline, void *reserved); |
Craig Tiller | 034929c | 2015-02-02 16:56:15 -0800 | [diff] [blame] | 179 | |
Craig Tiller | e2c6237 | 2015-12-07 16:11:03 -0800 | [diff] [blame] | 180 | /** Ping the channels peer (load balanced channels will select one sub-channel |
Craig Tiller | 26dab31 | 2015-12-07 14:43:47 -0800 | [diff] [blame] | 181 | to ping); if the channel is not connected, posts a failed. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 182 | GRPCAPI void grpc_channel_ping(grpc_channel *channel, grpc_completion_queue *cq, |
| 183 | void *tag, void *reserved); |
Craig Tiller | 26dab31 | 2015-12-07 14:43:47 -0800 | [diff] [blame] | 184 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 185 | /** Pre-register a method/host pair on a channel. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 186 | GRPCAPI void *grpc_channel_register_call(grpc_channel *channel, |
| 187 | const char *method, const char *host, |
| 188 | void *reserved); |
Craig Tiller | 0845337 | 2015-04-10 16:05:38 -0700 | [diff] [blame] | 189 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 190 | /** Create a call given a handle returned from grpc_channel_register_call */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 191 | GRPCAPI grpc_call *grpc_channel_create_registered_call( |
Craig Tiller | 7536af0 | 2015-12-22 13:49:30 -0800 | [diff] [blame] | 192 | grpc_channel *channel, grpc_call *parent_call, uint32_t propagation_mask, |
Craig Tiller | 3e7c6a7 | 2015-07-31 16:17:04 -0700 | [diff] [blame] | 193 | grpc_completion_queue *completion_queue, void *registered_call_handle, |
Nicolas "Pixel" Noble | 9d72b14 | 2015-08-08 01:45:38 +0200 | [diff] [blame] | 194 | gpr_timespec deadline, void *reserved); |
Craig Tiller | 0845337 | 2015-04-10 16:05:38 -0700 | [diff] [blame] | 195 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 196 | /** Start a batch of operations defined in the array ops; when complete, post a |
| 197 | completion of type 'tag' to the completion queue bound to the call. |
| 198 | The order of ops specified in the batch has no significance. |
| 199 | Only one operation of each type can be active at once in any given |
| 200 | batch. You must call grpc_completion_queue_next or |
| 201 | grpc_completion_queue_pluck on the completion queue associated with 'call' |
| 202 | for work to be performed. |
| 203 | THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment |
| 204 | needs to be synchronized. As an optimization, you may synchronize batches |
| 205 | containing just send operations independently from batches containing just |
| 206 | receive operations. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 207 | GRPCAPI grpc_call_error grpc_call_start_batch(grpc_call *call, |
| 208 | const grpc_op *ops, size_t nops, |
| 209 | void *tag, void *reserved); |
Craig Tiller | fef7669 | 2015-02-02 16:44:26 -0800 | [diff] [blame] | 210 | |
Craig Tiller | 4524942 | 2015-07-20 16:16:35 -0700 | [diff] [blame] | 211 | /** Returns a newly allocated string representing the endpoint to which this |
| 212 | call is communicating with. The string is in the uri format accepted by |
| 213 | grpc_channel_create. |
Alistair Veitch | ff32faf | 2015-07-30 09:54:15 -0700 | [diff] [blame] | 214 | The returned string should be disposed of with gpr_free(). |
Craig Tiller | 4524942 | 2015-07-20 16:16:35 -0700 | [diff] [blame] | 215 | |
| 216 | WARNING: this value is never authenticated or subject to any security |
| 217 | related code. It must not be used for any authentication related |
| 218 | functionality. Instead, use grpc_auth_context. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 219 | GRPCAPI char *grpc_call_get_peer(grpc_call *call); |
Craig Tiller | 1b22b9d | 2015-07-20 13:42:22 -0700 | [diff] [blame] | 220 | |
Alistair Veitch | ff32faf | 2015-07-30 09:54:15 -0700 | [diff] [blame] | 221 | struct census_context; |
| 222 | |
| 223 | /* Set census context for a call; Must be called before first call to |
| 224 | grpc_call_start_batch(). */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 225 | GRPCAPI void grpc_census_call_set_context(grpc_call *call, |
| 226 | struct census_context *context); |
Alistair Veitch | ff32faf | 2015-07-30 09:54:15 -0700 | [diff] [blame] | 227 | |
| 228 | /* Retrieve the calls current census context. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 229 | GRPCAPI struct census_context *grpc_census_call_get_context(grpc_call *call); |
Alistair Veitch | ff32faf | 2015-07-30 09:54:15 -0700 | [diff] [blame] | 230 | |
Craig Tiller | 4524942 | 2015-07-20 16:16:35 -0700 | [diff] [blame] | 231 | /** Return a newly allocated string representing the target a channel was |
| 232 | created for. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 233 | GRPCAPI char *grpc_channel_get_target(grpc_channel *channel); |
Craig Tiller | 4524942 | 2015-07-20 16:16:35 -0700 | [diff] [blame] | 234 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 235 | /** Create a client channel to 'target'. Additional channel level configuration |
| 236 | MAY be provided by grpc_channel_args, though the expectation is that most |
| 237 | clients will want to simply pass NULL. See grpc_channel_args definition for |
| 238 | more on this. The data in 'args' need only live through the invocation of |
| 239 | this function. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 240 | GRPCAPI grpc_channel *grpc_insecure_channel_create( |
Craig Tiller | d6546c9 | 2016-01-29 07:59:35 -0800 | [diff] [blame] | 241 | const char *target, const grpc_channel_args *args, void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 242 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 243 | /** Create a lame client: this client fails every operation attempted on it. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 244 | GRPCAPI grpc_channel *grpc_lame_client_channel_create( |
Craig Tiller | d6546c9 | 2016-01-29 07:59:35 -0800 | [diff] [blame] | 245 | const char *target, grpc_status_code error_code, const char *error_message); |
Craig Tiller | 42bc87c | 2015-02-23 08:50:19 -0800 | [diff] [blame] | 246 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 247 | /** Close and destroy a grpc channel */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 248 | GRPCAPI void grpc_channel_destroy(grpc_channel *channel); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 249 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 250 | /* Error handling for grpc_call |
| 251 | Most grpc_call functions return a grpc_error. If the error is not GRPC_OK |
| 252 | then the operation failed due to some unsatisfied precondition. |
| 253 | If a grpc_call fails, it's guaranteed that no change to the call state |
| 254 | has been made. */ |
| 255 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 256 | /** Called by clients to cancel an RPC on the server. |
| 257 | Can be called multiple times, from any thread. |
| 258 | THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status |
| 259 | are thread-safe, and can be called at any point before grpc_call_destroy |
| 260 | is called.*/ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 261 | GRPCAPI grpc_call_error grpc_call_cancel(grpc_call *call, void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 262 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 263 | /** Called by clients to cancel an RPC on the server. |
| 264 | Can be called multiple times, from any thread. |
| 265 | If a status has not been received for the call, set it to the status code |
| 266 | and description passed in. |
| 267 | Importantly, this function does not send status nor description to the |
| 268 | remote endpoint. */ |
Craig Tiller | f40df23 | 2016-03-25 13:38:14 -0700 | [diff] [blame] | 269 | GRPCAPI grpc_call_error grpc_call_cancel_with_status(grpc_call *call, |
| 270 | grpc_status_code status, |
| 271 | const char *description, |
| 272 | void *reserved); |
Craig Tiller | d248c24 | 2015-01-14 11:49:12 -0800 | [diff] [blame] | 273 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 274 | /** Destroy a call. |
| 275 | THREAD SAFETY: grpc_call_destroy is thread-compatible */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 276 | GRPCAPI void grpc_call_destroy(grpc_call *call); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 277 | |
David G. Quintas | b2a1c59 | 2015-08-20 14:44:27 -0700 | [diff] [blame] | 278 | /** Request notification of a new call. |
Craig Tiller | ddf3a51 | 2015-09-24 13:03:44 -0700 | [diff] [blame] | 279 | Once a call is received, a notification tagged with \a tag_new is added to |
| 280 | \a cq_for_notification. \a call, \a details and \a request_metadata are |
Craig Tiller | 1359a12 | 2015-08-24 14:43:32 -0700 | [diff] [blame] | 281 | updated with the appropriate call information. \a cq_bound_to_call is bound |
| 282 | to \a call, and batch operation notifications for that call will be posted |
| 283 | to \a cq_bound_to_call. |
David G. Quintas | b2a1c59 | 2015-08-20 14:44:27 -0700 | [diff] [blame] | 284 | Note that \a cq_for_notification must have been registered to the server via |
| 285 | \a grpc_server_register_completion_queue. */ |
Craig Tiller | f40df23 | 2016-03-25 13:38:14 -0700 | [diff] [blame] | 286 | GRPCAPI grpc_call_error grpc_server_request_call( |
| 287 | grpc_server *server, grpc_call **call, grpc_call_details *details, |
| 288 | grpc_metadata_array *request_metadata, |
| 289 | grpc_completion_queue *cq_bound_to_call, |
| 290 | grpc_completion_queue *cq_for_notification, void *tag_new); |
Craig Tiller | 034929c | 2015-02-02 16:56:15 -0800 | [diff] [blame] | 291 | |
Craig Tiller | 06cb1a9 | 2016-04-04 08:10:47 -0700 | [diff] [blame] | 292 | /** How to handle payloads for a registered method */ |
| 293 | typedef enum { |
| 294 | /** Don't try to read the payload */ |
| 295 | GRPC_SRM_PAYLOAD_NONE, |
| 296 | /** Read the initial payload as a byte buffer */ |
| 297 | GRPC_SRM_PAYLOAD_READ_INITIAL_BYTE_BUFFER |
| 298 | } grpc_server_register_method_payload_handling; |
| 299 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 300 | /** Registers a method in the server. |
| 301 | Methods to this (host, method) pair will not be reported by |
| 302 | grpc_server_request_call, but instead be reported by |
| 303 | grpc_server_request_registered_call when passed the appropriate |
| 304 | registered_method (as returned by this function). |
| 305 | Must be called before grpc_server_start. |
| 306 | Returns NULL on failure. */ |
Craig Tiller | 06cb1a9 | 2016-04-04 08:10:47 -0700 | [diff] [blame] | 307 | GRPCAPI void *grpc_server_register_method( |
| 308 | grpc_server *server, const char *method, const char *host, |
| 309 | grpc_server_register_method_payload_handling payload_handling, |
| 310 | uint32_t flags); |
Craig Tiller | 24be0f7 | 2015-02-10 14:04:22 -0800 | [diff] [blame] | 311 | |
Alistair Veitch | ff32faf | 2015-07-30 09:54:15 -0700 | [diff] [blame] | 312 | /** Request notification of a new pre-registered call. 'cq_for_notification' |
| 313 | must have been registered to the server via |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 314 | grpc_server_register_completion_queue. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 315 | GRPCAPI grpc_call_error grpc_server_request_registered_call( |
Craig Tiller | 24be0f7 | 2015-02-10 14:04:22 -0800 | [diff] [blame] | 316 | grpc_server *server, void *registered_method, grpc_call **call, |
| 317 | gpr_timespec *deadline, grpc_metadata_array *request_metadata, |
| 318 | grpc_byte_buffer **optional_payload, |
Craig Tiller | f9e6adf | 2015-05-06 11:45:59 -0700 | [diff] [blame] | 319 | grpc_completion_queue *cq_bound_to_call, |
| 320 | grpc_completion_queue *cq_for_notification, void *tag_new); |
Craig Tiller | 24be0f7 | 2015-02-10 14:04:22 -0800 | [diff] [blame] | 321 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 322 | /** Create a server. Additional configuration for each incoming channel can |
| 323 | be specified with args. If no additional configuration is needed, args can |
| 324 | be NULL. See grpc_channel_args for more. The data in 'args' need only live |
| 325 | through the invocation of this function. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 326 | GRPCAPI grpc_server *grpc_server_create(const grpc_channel_args *args, |
| 327 | void *reserved); |
Craig Tiller | f9e6adf | 2015-05-06 11:45:59 -0700 | [diff] [blame] | 328 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 329 | /** Register a completion queue with the server. Must be done for any |
| 330 | notification completion queue that is passed to grpc_server_request_*_call |
| 331 | and to grpc_server_shutdown_and_notify. Must be performed prior to |
| 332 | grpc_server_start. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 333 | GRPCAPI void grpc_server_register_completion_queue(grpc_server *server, |
| 334 | grpc_completion_queue *cq, |
| 335 | void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 336 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 337 | /** Add a HTTP2 over plaintext over tcp listener. |
| 338 | Returns bound port number on success, 0 on failure. |
| 339 | REQUIRES: server not started */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 340 | GRPCAPI int grpc_server_add_insecure_http2_port(grpc_server *server, |
| 341 | const char *addr); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 342 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 343 | /** Start a server - tells all listeners to start listening */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 344 | GRPCAPI void grpc_server_start(grpc_server *server); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 345 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 346 | /** Begin shutting down a server. |
| 347 | After completion, no new calls or connections will be admitted. |
| 348 | Existing calls will be allowed to complete. |
| 349 | Send a GRPC_OP_COMPLETE event when there are no more calls being serviced. |
| 350 | Shutdown is idempotent, and all tags will be notified at once if multiple |
| 351 | grpc_server_shutdown_and_notify calls are made. 'cq' must have been |
| 352 | registered to this server via grpc_server_register_completion_queue. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 353 | GRPCAPI void grpc_server_shutdown_and_notify(grpc_server *server, |
| 354 | grpc_completion_queue *cq, |
| 355 | void *tag); |
Craig Tiller | 4ffdcd5 | 2015-01-16 11:34:55 -0800 | [diff] [blame] | 356 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 357 | /** Cancel all in-progress calls. |
| 358 | Only usable after shutdown. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 359 | GRPCAPI void grpc_server_cancel_all_calls(grpc_server *server); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 360 | |
Craig Tiller | 2d984bf | 2015-07-20 15:01:38 -0700 | [diff] [blame] | 361 | /** Destroy a server. |
| 362 | Shutdown must have completed beforehand (i.e. all tags generated by |
| 363 | grpc_server_shutdown_and_notify must have been received, and at least |
| 364 | one call to grpc_server_shutdown_and_notify must have been made). */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 365 | GRPCAPI void grpc_server_destroy(grpc_server *server); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 366 | |
Craig Tiller | af7abf9 | 2015-06-03 17:18:58 -0700 | [diff] [blame] | 367 | /** Enable or disable a tracer. |
| 368 | |
| 369 | Tracers (usually controlled by the environment variable GRPC_TRACE) |
| 370 | allow printf-style debugging on GRPC internals, and are useful for |
Craig Tiller | 9a57633 | 2015-06-17 10:21:49 -0700 | [diff] [blame] | 371 | tracking down problems in the field. |
Craig Tiller | af7abf9 | 2015-06-03 17:18:58 -0700 | [diff] [blame] | 372 | |
Craig Tiller | 9a57633 | 2015-06-17 10:21:49 -0700 | [diff] [blame] | 373 | Use of this function is not strictly thread-safe, but the |
Craig Tiller | af7abf9 | 2015-06-03 17:18:58 -0700 | [diff] [blame] | 374 | thread-safety issues raised by it should not be of concern. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 375 | GRPCAPI int grpc_tracer_set_enabled(const char *name, int enabled); |
Craig Tiller | af7abf9 | 2015-06-03 17:18:58 -0700 | [diff] [blame] | 376 | |
murgatroid99 | c3910ca | 2016-01-06 13:14:23 -0800 | [diff] [blame] | 377 | /** Check whether a metadata key is legal (will be accepted by core) */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 378 | GRPCAPI int grpc_header_key_is_legal(const char *key, size_t length); |
murgatroid99 | c3910ca | 2016-01-06 13:14:23 -0800 | [diff] [blame] | 379 | |
| 380 | /** Check whether a non-binary metadata value is legal (will be accepted by |
| 381 | core) */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 382 | GRPCAPI int grpc_header_nonbin_value_is_legal(const char *value, size_t length); |
murgatroid99 | c3910ca | 2016-01-06 13:14:23 -0800 | [diff] [blame] | 383 | |
| 384 | /** Check whether a metadata key corresponds to a binary value */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 385 | GRPCAPI int grpc_is_binary_header(const char *key, size_t length); |
murgatroid99 | c3910ca | 2016-01-06 13:14:23 -0800 | [diff] [blame] | 386 | |
Yuchen Zeng | 2e7d957 | 2016-04-15 17:29:57 -0700 | [diff] [blame] | 387 | /** Convert grpc_call_error values to a string */ |
| 388 | GRPCAPI const char *grpc_call_error_to_string(grpc_call_error error); |
| 389 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 390 | #ifdef __cplusplus |
| 391 | } |
| 392 | #endif |
| 393 | |
Craig Tiller | b20111c | 2015-04-10 23:27:11 +0000 | [diff] [blame] | 394 | #endif /* GRPC_GRPC_H */ |