1 /* 2 * 3 * Copyright 2015-2016 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * 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, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #ifndef GRPC_GRPC_H 20 #define GRPC_GRPC_H 21 22 #include <stddef.h> 23 24 #include <grpc/byte_buffer.h> 25 #include <grpc/impl/connectivity_state.h> // IWYU pragma: export 26 #include <grpc/impl/grpc_types.h> // IWYU pragma: export 27 #include <grpc/impl/propagation_bits.h> 28 #include <grpc/slice.h> 29 #include <grpc/status.h> 30 #include <grpc/support/port_platform.h> 31 #include <grpc/support/time.h> 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 /*! \mainpage GRPC Core 38 * 39 * The GRPC Core library is a low-level library designed to be wrapped by higher 40 * level libraries. The top-level API is provided in grpc.h. Security related 41 * functionality lives in grpc_security.h. 42 */ 43 44 GRPCAPI void grpc_metadata_array_init(grpc_metadata_array* array); 45 GRPCAPI void grpc_metadata_array_destroy(grpc_metadata_array* array); 46 47 GRPCAPI void grpc_call_details_init(grpc_call_details* details); 48 GRPCAPI void grpc_call_details_destroy(grpc_call_details* details); 49 50 /** Initialize the grpc library. 51 52 After it's called, a matching invocation to grpc_shutdown() is expected. 53 54 It is not safe to call any other grpc functions before calling this. 55 (To avoid overhead, little checking is done, and some things may work. We 56 do not warrant that they will continue to do so in future revisions of this 57 library). */ 58 GRPCAPI void grpc_init(void); 59 60 /** Shut down the grpc library. 61 62 Before it's called, there should haven been a matching invocation to 63 grpc_init(). 64 65 The last call to grpc_shutdown will initiate cleaning up of grpc library 66 internals, which can happen in another thread. Once the clean-up is done, 67 no memory is used by grpc, nor are any instructions executing within the 68 grpc library. Prior to calling, all application owned grpc objects must 69 have been destroyed. */ 70 GRPCAPI void grpc_shutdown(void); 71 72 /** EXPERIMENTAL. Returns 1 if the grpc library has been initialized. 73 TODO(ericgribkoff) Decide if this should be promoted to non-experimental as 74 part of stabilizing the fork support API, as tracked in 75 https://github.com/grpc/grpc/issues/15334 */ 76 GRPCAPI int grpc_is_initialized(void); 77 78 /** DEPRECATED. Recommend to use grpc_shutdown only */ 79 GRPCAPI void grpc_shutdown_blocking(void); 80 81 /** Return a string representing the current version of grpc */ 82 GRPCAPI const char* grpc_version_string(void); 83 84 /** Return a string specifying what the 'g' in gRPC stands for */ 85 GRPCAPI const char* grpc_g_stands_for(void); 86 87 /** Returns the completion queue factory based on the attributes. MAY return a 88 NULL if no factory can be found */ 89 GRPCAPI const grpc_completion_queue_factory* 90 grpc_completion_queue_factory_lookup( 91 const grpc_completion_queue_attributes* attributes); 92 93 /** Helper function to create a completion queue with grpc_cq_completion_type 94 of GRPC_CQ_NEXT and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING */ 95 GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_next( 96 void* reserved); 97 98 /** Helper function to create a completion queue with grpc_cq_completion_type 99 of GRPC_CQ_PLUCK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING */ 100 GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_pluck( 101 void* reserved); 102 103 /** Helper function to create a completion queue with grpc_cq_completion_type 104 of GRPC_CQ_CALLBACK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING. 105 This function is experimental. */ 106 GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_callback( 107 grpc_completion_queue_functor* shutdown_callback, void* reserved); 108 109 /** Create a completion queue */ 110 GRPCAPI grpc_completion_queue* grpc_completion_queue_create( 111 const grpc_completion_queue_factory* factory, 112 const grpc_completion_queue_attributes* attributes, void* reserved); 113 114 /** Blocks until an event is available, the completion queue is being shut down, 115 or deadline is reached. 116 117 Returns a grpc_event with type GRPC_QUEUE_TIMEOUT on timeout, 118 otherwise a grpc_event describing the event that occurred. 119 120 Callers must not call grpc_completion_queue_next and 121 grpc_completion_queue_pluck simultaneously on the same completion queue. */ 122 GRPCAPI grpc_event grpc_completion_queue_next(grpc_completion_queue* cq, 123 gpr_timespec deadline, 124 void* reserved); 125 126 /** Blocks until an event with tag 'tag' is available, the completion queue is 127 being shutdown or deadline is reached. 128 129 Returns a grpc_event with type GRPC_QUEUE_TIMEOUT on timeout, 130 otherwise a grpc_event describing the event that occurred. 131 132 Callers must not call grpc_completion_queue_next and 133 grpc_completion_queue_pluck simultaneously on the same completion queue. 134 135 Completion queues support a maximum of GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 136 concurrently executing plucks at any time. */ 137 GRPCAPI grpc_event grpc_completion_queue_pluck(grpc_completion_queue* cq, 138 void* tag, gpr_timespec deadline, 139 void* reserved); 140 141 /** Maximum number of outstanding grpc_completion_queue_pluck executions per 142 completion queue */ 143 #define GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 6 144 145 /** Begin destruction of a completion queue. Once all possible events are 146 drained then grpc_completion_queue_next will start to produce 147 GRPC_QUEUE_SHUTDOWN events only. At that point it's safe to call 148 grpc_completion_queue_destroy. 149 150 After calling this function applications should ensure that no 151 NEW work is added to be published on this completion queue. */ 152 GRPCAPI void grpc_completion_queue_shutdown(grpc_completion_queue* cq); 153 154 /** Destroy a completion queue. The caller must ensure that the queue is 155 drained and no threads are executing grpc_completion_queue_next */ 156 GRPCAPI void grpc_completion_queue_destroy(grpc_completion_queue* cq); 157 158 /*********** EXPERIMENTAL API ************/ 159 /** Initializes a thread local cache for \a cq. 160 * grpc_flush_cq_tls_cache() MUST be called on the same thread, 161 * with the same cq. 162 */ 163 GRPCAPI void grpc_completion_queue_thread_local_cache_init( 164 grpc_completion_queue* cq); 165 166 /*********** EXPERIMENTAL API ************/ 167 /** Flushes the thread local cache for \a cq. 168 * Returns 1 if there was contents in the cache. If there was an event 169 * in \a cq tls cache, its tag is placed in tag, and ok is set to the 170 * event success. 171 */ 172 GRPCAPI int grpc_completion_queue_thread_local_cache_flush( 173 grpc_completion_queue* cq, void** tag, int* ok); 174 175 /** Check the connectivity state of a channel. */ 176 GRPCAPI grpc_connectivity_state grpc_channel_check_connectivity_state( 177 grpc_channel* channel, int try_to_connect); 178 179 /** Watch for a change in connectivity state. 180 Once the channel connectivity state is different from last_observed_state, 181 tag will be enqueued on cq with success=1. 182 If deadline expires BEFORE the state is changed, tag will be enqueued on cq 183 with success=0. */ 184 GRPCAPI void grpc_channel_watch_connectivity_state( 185 grpc_channel* channel, grpc_connectivity_state last_observed_state, 186 gpr_timespec deadline, grpc_completion_queue* cq, void* tag); 187 188 /** Check whether a grpc channel supports connectivity watcher */ 189 GRPCAPI int grpc_channel_support_connectivity_watcher(grpc_channel* channel); 190 191 /** Create a call given a grpc_channel, in order to call 'method'. All 192 completions are sent to 'completion_queue'. 'method' and 'host' need only 193 live through the invocation of this function. 194 If parent_call is non-NULL, it must be a server-side call. It will be used 195 to propagate properties from the server call to this new client call, 196 depending on the value of \a propagation_mask (see propagation_bits.h for 197 possible values). */ 198 GRPCAPI grpc_call* grpc_channel_create_call( 199 grpc_channel* channel, grpc_call* parent_call, uint32_t propagation_mask, 200 grpc_completion_queue* completion_queue, grpc_slice method, 201 const grpc_slice* host, gpr_timespec deadline, void* reserved); 202 203 /** Pre-register a method/host pair on a channel. 204 method and host are not owned and must remain alive while the channel is 205 alive. */ 206 GRPCAPI void* grpc_channel_register_call(grpc_channel* channel, 207 const char* method, const char* host, 208 void* reserved); 209 210 /** Create a call given a handle returned from grpc_channel_register_call. 211 \sa grpc_channel_create_call. */ 212 GRPCAPI grpc_call* grpc_channel_create_registered_call( 213 grpc_channel* channel, grpc_call* parent_call, uint32_t propagation_mask, 214 grpc_completion_queue* completion_queue, void* registered_call_handle, 215 gpr_timespec deadline, void* reserved); 216 217 /** Allocate memory in the grpc_call arena: this memory is automatically 218 discarded at call completion */ 219 GRPCAPI void* grpc_call_arena_alloc(grpc_call* call, size_t size); 220 221 /** Start a batch of operations defined in the array ops; when complete, post a 222 completion of type 'tag' to the completion queue bound to the call. 223 The order of ops specified in the batch has no significance. 224 Only one operation of each type can be active at once in any given 225 batch. 226 If a call to grpc_call_start_batch returns GRPC_CALL_OK you must call 227 grpc_completion_queue_next or grpc_completion_queue_pluck on the completion 228 queue associated with 'call' for work to be performed. If a call to 229 grpc_call_start_batch returns any value other than GRPC_CALL_OK it is 230 guaranteed that no state associated with 'call' is changed and it is not 231 appropriate to call grpc_completion_queue_next or 232 grpc_completion_queue_pluck consequent to the failed grpc_call_start_batch 233 call. 234 If a call to grpc_call_start_batch with an empty batch returns 235 GRPC_CALL_OK, the tag is put in the completion queue immediately. 236 THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment 237 needs to be synchronized. As an optimization, you may synchronize batches 238 containing just send operations independently from batches containing just 239 receive operations. Access to grpc_call_start_batch with an empty batch is 240 thread-compatible. */ 241 GRPCAPI grpc_call_error grpc_call_start_batch(grpc_call* call, 242 const grpc_op* ops, size_t nops, 243 void* tag, void* reserved); 244 245 /** Returns a newly allocated string representing the endpoint to which this 246 call is communicating with. The string is in the uri format accepted by 247 grpc_channel_create. 248 The returned string should be disposed of with gpr_free(). 249 250 WARNING: this value is never authenticated or subject to any security 251 related code. It must not be used for any authentication related 252 functionality. Instead, use grpc_auth_context. */ 253 GRPCAPI char* grpc_call_get_peer(grpc_call* call); 254 255 struct census_context; 256 257 /** Set census context for a call; Must be called before first call to 258 grpc_call_start_batch(). */ 259 GRPCAPI void grpc_census_call_set_context(grpc_call* call, 260 struct census_context* context); 261 262 /** Retrieve the calls current census context. */ 263 GRPCAPI struct census_context* grpc_census_call_get_context(grpc_call* call); 264 265 /** Return a newly allocated string representing the target a channel was 266 created for. */ 267 GRPCAPI char* grpc_channel_get_target(grpc_channel* channel); 268 269 /** Request info about the channel. 270 \a channel_info indicates what information is being requested and 271 how that information will be returned. 272 \a channel_info is owned by the caller. */ 273 GRPCAPI void grpc_channel_get_info(grpc_channel* channel, 274 const grpc_channel_info* channel_info); 275 276 /** EXPERIMENTAL. Resets the channel's connect backoff. 277 TODO(roth): When we see whether this proves useful, either promote 278 to non-experimental or remove it. */ 279 GRPCAPI void grpc_channel_reset_connect_backoff(grpc_channel* channel); 280 281 /** --- grpc_channel_credentials object. --- 282 283 A channel credentials object represents a way to authenticate a client on a 284 channel. Different types of channel credentials are declared in 285 grpc_security.h. */ 286 287 typedef struct grpc_channel_credentials grpc_channel_credentials; 288 289 /** Releases a channel credentials object. 290 The creator of the credentials object is responsible for its release. */ 291 292 GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials* creds); 293 294 /** --- grpc_server_credentials object. --- 295 296 A server credentials object represents a way to authenticate a server. 297 Different types of server credentials are declared in grpc_security.h. */ 298 299 typedef struct grpc_server_credentials grpc_server_credentials; 300 301 /** Releases a server_credentials object. 302 The creator of the server_credentials object is responsible for its release. 303 */ 304 GRPCAPI void grpc_server_credentials_release(grpc_server_credentials* creds); 305 306 /** Creates a secure channel using the passed-in credentials. Additional 307 channel level configuration MAY be provided by grpc_channel_args, though 308 the expectation is that most clients will want to simply pass NULL. The 309 user data in 'args' need only live through the invocation of this function. 310 However, if any args of the 'pointer' type are passed, then the referenced 311 vtable must be maintained by the caller until grpc_channel_destroy 312 terminates. See grpc_channel_args definition for more on this. */ 313 GRPCAPI grpc_channel* grpc_channel_create(const char* target, 314 grpc_channel_credentials* creds, 315 const grpc_channel_args* args); 316 317 /** Create a lame client: this client fails every operation attempted on it. */ 318 GRPCAPI grpc_channel* grpc_lame_client_channel_create( 319 const char* target, grpc_status_code error_code, const char* error_message); 320 321 /** Close and destroy a grpc channel */ 322 GRPCAPI void grpc_channel_destroy(grpc_channel* channel); 323 324 /** Error handling for grpc_call 325 Most grpc_call functions return a grpc_error. If the error is not GRPC_OK 326 then the operation failed due to some unsatisfied precondition. 327 If a grpc_call fails, it's guaranteed that no change to the call state 328 has been made. */ 329 330 /** Cancel an RPC. 331 Can be called multiple times, from any thread. 332 THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status 333 are thread-safe, and can be called at any point before grpc_call_unref 334 is called.*/ 335 GRPCAPI grpc_call_error grpc_call_cancel(grpc_call* call, void* reserved); 336 337 /** Cancel an RPC. 338 Can be called multiple times, from any thread. 339 If a status has not been received for the call, set it to the status code 340 and description passed in. 341 Importantly, this function does not send status nor description to the 342 remote endpoint. 343 Note that \a description doesn't need be a static string. 344 It doesn't need to be alive after the call to 345 grpc_call_cancel_with_status completes. 346 */ 347 GRPCAPI grpc_call_error grpc_call_cancel_with_status(grpc_call* call, 348 grpc_status_code status, 349 const char* description, 350 void* reserved); 351 352 /* Returns whether or not the call's receive message operation failed because of 353 * an error (as opposed to a graceful end-of-stream) */ 354 GRPCAPI int grpc_call_failed_before_recv_message(const grpc_call* c); 355 356 /** Ref a call. 357 THREAD SAFETY: grpc_call_ref is thread-compatible */ 358 GRPCAPI void grpc_call_ref(grpc_call* call); 359 360 /** Unref a call. 361 THREAD SAFETY: grpc_call_unref is thread-compatible */ 362 GRPCAPI void grpc_call_unref(grpc_call* call); 363 364 /** Request notification of a new call. 365 Once a call is received, a notification tagged with \a tag_new is added to 366 \a cq_for_notification. \a call, \a details and \a request_metadata are 367 updated with the appropriate call information. \a cq_bound_to_call is bound 368 to \a call, and batch operation notifications for that call will be posted 369 to \a cq_bound_to_call. 370 Note that \a cq_for_notification must have been registered to the server via 371 \a grpc_server_register_completion_queue. */ 372 GRPCAPI grpc_call_error grpc_server_request_call( 373 grpc_server* server, grpc_call** call, grpc_call_details* details, 374 grpc_metadata_array* request_metadata, 375 grpc_completion_queue* cq_bound_to_call, 376 grpc_completion_queue* cq_for_notification, void* tag_new); 377 378 /** How to handle payloads for a registered method */ 379 typedef enum { 380 /** Don't try to read the payload */ 381 GRPC_SRM_PAYLOAD_NONE, 382 /** Read the initial payload as a byte buffer */ 383 GRPC_SRM_PAYLOAD_READ_INITIAL_BYTE_BUFFER 384 } grpc_server_register_method_payload_handling; 385 386 /** Registers a method in the server. 387 Methods to this (host, method) pair will not be reported by 388 grpc_server_request_call, but instead be reported by 389 grpc_server_request_registered_call when passed the appropriate 390 registered_method (as returned by this function). 391 Must be called before grpc_server_start. 392 Returns NULL on failure. */ 393 GRPCAPI void* grpc_server_register_method( 394 grpc_server* server, const char* method, const char* host, 395 grpc_server_register_method_payload_handling payload_handling, 396 uint32_t flags); 397 398 /** Request notification of a new pre-registered call. 'cq_for_notification' 399 must have been registered to the server via 400 grpc_server_register_completion_queue. */ 401 GRPCAPI grpc_call_error grpc_server_request_registered_call( 402 grpc_server* server, void* registered_method, grpc_call** call, 403 gpr_timespec* deadline, grpc_metadata_array* request_metadata, 404 grpc_byte_buffer** optional_payload, 405 grpc_completion_queue* cq_bound_to_call, 406 grpc_completion_queue* cq_for_notification, void* tag_new); 407 408 /** Create a server. Additional configuration for each incoming channel can 409 be specified with args. If no additional configuration is needed, args can 410 be NULL. The user data in 'args' need only live through the invocation of 411 this function. However, if any args of the 'pointer' type are passed, then 412 the referenced vtable must be maintained by the caller until 413 grpc_server_destroy terminates. See grpc_channel_args definition for more 414 on this. */ 415 GRPCAPI grpc_server* grpc_server_create(const grpc_channel_args* args, 416 void* reserved); 417 418 /** Register a completion queue with the server. Must be done for any 419 notification completion queue that is passed to grpc_server_request_*_call 420 and to grpc_server_shutdown_and_notify. Must be performed prior to 421 grpc_server_start. */ 422 GRPCAPI void grpc_server_register_completion_queue(grpc_server* server, 423 grpc_completion_queue* cq, 424 void* reserved); 425 426 // More members might be added in later, so users should take care to memset 427 // this to 0 before using it. 428 typedef struct { 429 grpc_status_code code; 430 const char* error_message; 431 } grpc_serving_status_update; 432 433 // There might be more methods added later, so users should take care to memset 434 // this to 0 before using it. 435 typedef struct { 436 void (*on_serving_status_update)(void* user_data, const char* uri, 437 grpc_serving_status_update update); 438 void* user_data; 439 } grpc_server_xds_status_notifier; 440 441 typedef struct grpc_server_config_fetcher grpc_server_config_fetcher; 442 443 /** EXPERIMENTAL. Creates an xDS config fetcher. */ 444 GRPCAPI grpc_server_config_fetcher* grpc_server_config_fetcher_xds_create( 445 grpc_server_xds_status_notifier notifier, const grpc_channel_args* args); 446 447 /** EXPERIMENTAL. Destroys a config fetcher. */ 448 GRPCAPI void grpc_server_config_fetcher_destroy( 449 grpc_server_config_fetcher* config_fetcher); 450 451 /** EXPERIMENTAL. Sets the server's config fetcher. Takes ownership. 452 Must be called before adding ports */ 453 GRPCAPI void grpc_server_set_config_fetcher( 454 grpc_server* server, grpc_server_config_fetcher* config_fetcher); 455 456 /** Add a HTTP2 over an encrypted link over tcp listener. 457 Returns bound port number on success, 0 on failure. 458 REQUIRES: server not started */ 459 GRPCAPI int grpc_server_add_http2_port(grpc_server* server, const char* addr, 460 grpc_server_credentials* creds); 461 462 /** Start a server - tells all listeners to start listening */ 463 GRPCAPI void grpc_server_start(grpc_server* server); 464 465 /** Begin shutting down a server. 466 After completion, no new calls or connections will be admitted. 467 Existing calls will be allowed to complete. 468 Send a GRPC_OP_COMPLETE event when there are no more calls being serviced. 469 Shutdown is idempotent, and all tags will be notified at once if multiple 470 grpc_server_shutdown_and_notify calls are made. 'cq' must have been 471 registered to this server via grpc_server_register_completion_queue. */ 472 GRPCAPI void grpc_server_shutdown_and_notify(grpc_server* server, 473 grpc_completion_queue* cq, 474 void* tag); 475 476 /** Cancel all in-progress calls. 477 Only usable after shutdown. */ 478 GRPCAPI void grpc_server_cancel_all_calls(grpc_server* server); 479 480 /** Destroy a server. 481 Shutdown must have completed beforehand (i.e. all tags generated by 482 grpc_server_shutdown_and_notify must have been received, and at least 483 one call to grpc_server_shutdown_and_notify must have been made). */ 484 GRPCAPI void grpc_server_destroy(grpc_server* server); 485 486 /** Enable or disable a tracer. 487 488 Tracers (usually controlled by the environment variable GRPC_TRACE) 489 allow printf-style debugging on GRPC internals, and are useful for 490 tracking down problems in the field. 491 492 Use of this function is not strictly thread-safe, but the 493 thread-safety issues raised by it should not be of concern. */ 494 GRPCAPI int grpc_tracer_set_enabled(const char* name, int enabled); 495 496 /** Check whether a metadata key is legal (will be accepted by core) */ 497 GRPCAPI int grpc_header_key_is_legal(grpc_slice slice); 498 499 /** Check whether a non-binary metadata value is legal (will be accepted by 500 core) */ 501 GRPCAPI int grpc_header_nonbin_value_is_legal(grpc_slice slice); 502 503 /** Check whether a metadata key corresponds to a binary value */ 504 GRPCAPI int grpc_is_binary_header(grpc_slice slice); 505 506 /** Convert grpc_call_error values to a string */ 507 GRPCAPI const char* grpc_call_error_to_string(grpc_call_error error); 508 509 /** Create a buffer pool */ 510 GRPCAPI grpc_resource_quota* grpc_resource_quota_create(const char* trace_name); 511 512 /** Add a reference to a buffer pool */ 513 GRPCAPI void grpc_resource_quota_ref(grpc_resource_quota* resource_quota); 514 515 /** Drop a reference to a buffer pool */ 516 GRPCAPI void grpc_resource_quota_unref(grpc_resource_quota* resource_quota); 517 518 /** Update the size of a buffer pool */ 519 GRPCAPI void grpc_resource_quota_resize(grpc_resource_quota* resource_quota, 520 size_t new_size); 521 522 /** Update the size of the maximum number of threads allowed */ 523 GRPCAPI void grpc_resource_quota_set_max_threads( 524 grpc_resource_quota* resource_quota, int new_max_threads); 525 526 /** EXPERIMENTAL. Dumps xDS configs as a serialized ClientConfig proto. 527 The full name of the proto is envoy.service.status.v3.ClientConfig. */ 528 GRPCAPI grpc_slice grpc_dump_xds_configs(void); 529 530 /** Fetch a vtable for a grpc_channel_arg that points to a grpc_resource_quota 531 */ 532 GRPCAPI const grpc_arg_pointer_vtable* grpc_resource_quota_arg_vtable(void); 533 534 /************* CHANNELZ API *************/ 535 /** Channelz is under active development. The following APIs will see some 536 churn as the feature is implemented. This comment will be removed once 537 channelz is officially supported, and these APIs become stable. For now 538 you may track the progress by following this github issue: 539 https://github.com/grpc/grpc/issues/15340 540 541 the following APIs return allocated JSON strings that match the response 542 objects from the channelz proto, found here: 543 https://github.com/grpc/grpc/blob/master/src/proto/grpc/channelz/channelz.proto. 544 545 For easy conversion to protobuf, The JSON is formatted according to: 546 https://developers.google.com/protocol-buffers/docs/proto3#json. */ 547 548 /* Gets all root channels (i.e. channels the application has directly 549 created). This does not include subchannels nor non-top level channels. 550 The returned string is allocated and must be freed by the application. */ 551 GRPCAPI char* grpc_channelz_get_top_channels(intptr_t start_channel_id); 552 553 /* Gets all servers that exist in the process. */ 554 GRPCAPI char* grpc_channelz_get_servers(intptr_t start_server_id); 555 556 /* Returns a single Server, or else a NOT_FOUND code. */ 557 GRPCAPI char* grpc_channelz_get_server(intptr_t server_id); 558 559 /* Gets all server sockets that exist in the server. */ 560 GRPCAPI char* grpc_channelz_get_server_sockets(intptr_t server_id, 561 intptr_t start_socket_id, 562 intptr_t max_results); 563 564 /* Returns a single Channel, or else a NOT_FOUND code. The returned string 565 is allocated and must be freed by the application. */ 566 GRPCAPI char* grpc_channelz_get_channel(intptr_t channel_id); 567 568 /* Returns a single Subchannel, or else a NOT_FOUND code. The returned string 569 is allocated and must be freed by the application. */ 570 GRPCAPI char* grpc_channelz_get_subchannel(intptr_t subchannel_id); 571 572 /* Returns a single Socket, or else a NOT_FOUND code. The returned string 573 is allocated and must be freed by the application. */ 574 GRPCAPI char* grpc_channelz_get_socket(intptr_t socket_id); 575 576 /** 577 * EXPERIMENTAL - Subject to change. 578 * Fetch a vtable for grpc_channel_arg that points to 579 * grpc_authorization_policy_provider. 580 */ 581 GRPCAPI const grpc_arg_pointer_vtable* 582 grpc_authorization_policy_provider_arg_vtable(void); 583 584 #ifdef __cplusplus 585 } 586 #endif 587 588 #endif /* GRPC_GRPC_H */ 589