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