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