GRPC Core  18.0.0
grpc.h
Go to the documentation of this file.
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 
23 
24 #include <grpc/status.h>
25 
26 #include <grpc/byte_buffer.h>
30 #include <grpc/slice.h>
31 #include <grpc/support/time.h>
32 #include <stddef.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
47 
50 
59 GRPCAPI void grpc_register_plugin(void (*init)(void), void (*destroy)(void));
60 
69 GRPCAPI void grpc_init(void);
70 
81 GRPCAPI void grpc_shutdown(void);
82 
88 
91 
93 GRPCAPI const char* grpc_version_string(void);
94 
96 GRPCAPI const char* grpc_g_stands_for(void);
97 
102  const grpc_completion_queue_attributes* attributes);
103 
107  void* reserved);
108 
112  void* reserved);
113 
118  grpc_completion_queue_functor* shutdown_callback, void* reserved);
119 
122  const grpc_completion_queue_factory* factory,
123  const grpc_completion_queue_attributes* attributes, void* reserved);
124 
134  gpr_timespec deadline,
135  void* reserved);
136 
149  void* tag, gpr_timespec deadline,
150  void* reserved);
151 
154 #define GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 6
155 
164 
168 
169 /*********** EXPERIMENTAL API ************/
176 
177 /*********** EXPERIMENTAL API ************/
184  grpc_completion_queue* cq, void** tag, int* ok);
185 
188  grpc_channel* channel, int try_to_connect);
189 
194  grpc_channel* channel);
195 
202  grpc_channel* channel, grpc_connectivity_state last_observed_state,
203  gpr_timespec deadline, grpc_completion_queue* cq, void* tag);
204 
207 
216  grpc_channel* channel, grpc_call* parent_call, uint32_t propagation_mask,
217  grpc_completion_queue* completion_queue, grpc_slice method,
218  const grpc_slice* host, gpr_timespec deadline, void* reserved);
219 
224  const char* method, const char* host,
225  void* reserved);
226 
230  grpc_channel* channel, grpc_call* parent_call, uint32_t propagation_mask,
231  grpc_completion_queue* completion_queue, void* registered_call_handle,
232  gpr_timespec deadline, void* reserved);
233 
236 GRPCAPI void* grpc_call_arena_alloc(grpc_call* call, size_t size);
237 
259  const grpc_op* ops, size_t nops,
260  void* tag, void* reserved);
261 
271 
272 struct census_context;
273 
277  struct census_context* context);
278 
281 
285 
291  const grpc_channel_info* channel_info);
292 
297 
306  const char* target, const grpc_channel_args* args, void* reserved);
307 
310  const char* target, grpc_status_code error_code, const char* error_message);
311 
314 
326 GRPCAPI grpc_call_error grpc_call_cancel(grpc_call* call, void* reserved);
327 
339  grpc_status_code status,
340  const char* description,
341  void* reserved);
342 
345 GRPCAPI void grpc_call_ref(grpc_call* call);
346 
349 GRPCAPI void grpc_call_unref(grpc_call* call);
350 
360  grpc_server* server, grpc_call** call, grpc_call_details* details,
361  grpc_metadata_array* request_metadata,
362  grpc_completion_queue* cq_bound_to_call,
363  grpc_completion_queue* cq_for_notification, void* tag_new);
364 
366 typedef enum {
372 
381  grpc_server* server, const char* method, const char* host,
383  uint32_t flags);
384 
389  grpc_server* server, void* registered_method, grpc_call** call,
390  gpr_timespec* deadline, grpc_metadata_array* request_metadata,
391  grpc_byte_buffer** optional_payload,
392  grpc_completion_queue* cq_bound_to_call,
393  grpc_completion_queue* cq_for_notification, void* tag_new);
394 
403  void* reserved);
404 
411  void* reserved);
412 
413 // There might be more methods added later, so users should take care to memset
414 // this to 0 before using it.
415 typedef struct {
416  void (*on_serving_status_update)(void* user_data, const char* uri,
417  grpc_status_code code,
418  const char* error_message);
419  void* user_data;
421 
423 
426  grpc_server_xds_status_notifier notifier, const grpc_channel_args* args);
427 
430  grpc_server_config_fetcher* config_fetcher);
431 
435  grpc_server* server, grpc_server_config_fetcher* config_fetcher);
436 
441  const char* addr);
442 
445 
455  void* tag);
456 
460 
466 
475 GRPCAPI int grpc_tracer_set_enabled(const char* name, int enabled);
476 
479 
483 
486 
489 
492 
495 
498 
501  size_t new_size);
502 
505  grpc_resource_quota* resource_quota, int new_max_threads);
506 
510 
514 
515 /************* CHANNELZ API *************/
529 /* Gets all root channels (i.e. channels the application has directly
530  created). This does not include subchannels nor non-top level channels.
531  The returned string is allocated and must be freed by the application. */
532 GRPCAPI char* grpc_channelz_get_top_channels(intptr_t start_channel_id);
533 
534 /* Gets all servers that exist in the process. */
535 GRPCAPI char* grpc_channelz_get_servers(intptr_t start_server_id);
536 
537 /* Returns a single Server, or else a NOT_FOUND code. */
538 GRPCAPI char* grpc_channelz_get_server(intptr_t server_id);
539 
540 /* Gets all server sockets that exist in the server. */
541 GRPCAPI char* grpc_channelz_get_server_sockets(intptr_t server_id,
542  intptr_t start_socket_id,
543  intptr_t max_results);
544 
545 /* Returns a single Channel, or else a NOT_FOUND code. The returned string
546  is allocated and must be freed by the application. */
547 GRPCAPI char* grpc_channelz_get_channel(intptr_t channel_id);
548 
549 /* Returns a single Subchannel, or else a NOT_FOUND code. The returned string
550  is allocated and must be freed by the application. */
551 GRPCAPI char* grpc_channelz_get_subchannel(intptr_t subchannel_id);
552 
553 /* Returns a single Socket, or else a NOT_FOUND code. The returned string
554  is allocated and must be freed by the application. */
555 GRPCAPI char* grpc_channelz_get_socket(intptr_t socket_id);
556 
564 
565 #ifdef __cplusplus
566 }
567 #endif
568 
569 #endif /* GRPC_GRPC_H */
struct census_context census_context
A Census Context is a handle used by Census to represent the current tracing and stats collection inf...
Definition: census.h:34
GRPCAPI grpc_event grpc_completion_queue_pluck(grpc_completion_queue *cq, void *tag, gpr_timespec deadline, void *reserved)
Blocks until an event with tag 'tag' is available, the completion queue is being shutdown or deadline...
Definition: completion_queue.cc:1327
GRPCAPI void grpc_server_config_fetcher_destroy(grpc_server_config_fetcher *config_fetcher)
EXPERIMENTAL.
Definition: server.cc:1607
GRPCAPI grpc_call_error grpc_server_request_registered_call(grpc_server *server, void *registered_method, grpc_call **call, gpr_timespec *deadline, grpc_metadata_array *request_metadata, grpc_byte_buffer **optional_payload, grpc_completion_queue *cq_bound_to_call, grpc_completion_queue *cq_for_notification, void *tag_new)
Request notification of a new pre-registered call.
Definition: server.cc:1572
GRPCAPI void grpc_server_register_completion_queue(grpc_server *server, grpc_completion_queue *cq, void *reserved)
Register a completion queue with the server.
Definition: server.cc:1492
GRPCAPI void grpc_metadata_array_init(grpc_metadata_array *array)
Definition: metadata_array.cc:28
GRPCAPI int grpc_is_initialized(void)
EXPERIMENTAL.
Definition: init.cc:250
GRPCAPI grpc_slice grpc_dump_xds_configs()
EXPERIMENTAL.
Definition: xds_client.cc:2505
GRPCAPI int grpc_header_key_is_legal(grpc_slice slice)
Check whether a metadata key is legal (will be accepted by core)
Definition: validate_metadata.cc:81
GRPCAPI int grpc_channel_support_connectivity_watcher(grpc_channel *channel)
Check whether a grpc channel supports connectivity watcher.
Definition: channel_connectivity.cc:59
GRPCAPI void grpc_shutdown(void)
Shut down the grpc library.
Definition: init.cc:212
GRPCAPI void grpc_call_ref(grpc_call *call)
Ref a call.
Definition: call.cc:579
GRPCAPI const grpc_arg_pointer_vtable * grpc_resource_quota_arg_vtable(void)
Fetch a vtable for a grpc_channel_arg that points to a grpc_resource_quota.
Definition: resource_quota.cc:768
GRPCAPI void grpc_channel_destroy(grpc_channel *channel)
Close and destroy a grpc channel.
Definition: channel.cc:531
GRPCAPI void grpc_completion_queue_shutdown(grpc_completion_queue *cq)
Begin destruction of a completion queue.
Definition: completion_queue.cc:1415
GRPCAPI char * grpc_channelz_get_subchannel(intptr_t subchannel_id)
Definition: channelz_registry.cc:254
GRPCAPI char * grpc_channelz_get_servers(intptr_t start_server_id)
Definition: channelz_registry.cc:191
GRPCAPI grpc_completion_queue * grpc_completion_queue_create_for_callback(grpc_completion_queue_functor *shutdown_callback, void *reserved)
Helper function to create a completion queue with grpc_cq_completion_type of GRPC_CQ_CALLBACK and grp...
Definition: completion_queue_factory.cc:74
GRPCAPI char * grpc_channelz_get_server_sockets(intptr_t server_id, intptr_t start_socket_id, intptr_t max_results)
Definition: channelz_registry.cc:215
GRPCAPI const grpc_arg_pointer_vtable * grpc_authorization_policy_provider_arg_vtable(void)
EXPERIMENTAL - Subject to change.
Definition: authorization_policy_provider_vtable.cc:42
GRPCAPI void grpc_channel_watch_connectivity_state(grpc_channel *channel, grpc_connectivity_state last_observed_state, gpr_timespec deadline, grpc_completion_queue *cq, void *tag)
Watch for a change in connectivity state.
Definition: channel_connectivity.cc:224
GRPCAPI void grpc_init(void)
Initialize the grpc library.
Definition: init.cc:128
GRPCAPI void grpc_channel_reset_connect_backoff(grpc_channel *channel)
EXPERIMENTAL.
Definition: channel.cc:333
GRPCAPI void grpc_server_shutdown_and_notify(grpc_server *server, grpc_completion_queue *cq, void *tag)
Begin shutting down a server.
Definition: server.cc:1529
GRPCAPI grpc_call_error grpc_call_cancel_with_status(grpc_call *call, grpc_status_code status, const char *description, void *reserved)
Cancel an RPC.
Definition: call.cc:674
GRPCAPI int grpc_server_add_insecure_http2_port(grpc_server *server, const char *addr)
Add a HTTP2 over plaintext over tcp listener.
Definition: server_chttp2.cc:39
GRPCAPI void grpc_metadata_array_destroy(grpc_metadata_array *array)
Definition: metadata_array.cc:33
GRPCAPI const char * grpc_g_stands_for(void)
Return a string specifying what the 'g' in gRPC stands for.
Definition: version.cc:28
GRPCAPI int grpc_is_binary_header(grpc_slice slice)
Check whether a metadata key corresponds to a binary value.
Definition: validate_metadata.cc:103
GRPCAPI void grpc_server_set_config_fetcher(grpc_server *server, grpc_server_config_fetcher *config_fetcher)
EXPERIMENTAL.
Definition: server.cc:1597
GRPCAPI grpc_completion_queue * grpc_completion_queue_create_for_next(void *reserved)
Helper function to create a completion queue with grpc_cq_completion_type of GRPC_CQ_NEXT and grpc_cq...
Definition: completion_queue_factory.cc:60
GRPCAPI grpc_call_error grpc_call_start_batch(grpc_call *call, const grpc_op *ops, size_t nops, void *tag, void *reserved)
Start a batch of operations defined in the array ops; when complete, post a completion of type 'tag' ...
Definition: call.cc:1976
GRPCAPI void grpc_resource_quota_unref(grpc_resource_quota *resource_quota)
Drop a reference to a buffer pool.
Definition: resource_quota.cc:687
GRPCAPI grpc_connectivity_state grpc_channel_check_connectivity_state(grpc_channel *channel, int try_to_connect)
Check the connectivity state of a channel.
Definition: channel_connectivity.cc:28
GRPCAPI grpc_server_config_fetcher * grpc_server_config_fetcher_xds_create(grpc_server_xds_status_notifier notifier, const grpc_channel_args *args)
EXPERIMENTAL.
Definition: xds_server_config_fetcher.cc:523
GRPCAPI const char * grpc_version_string(void)
Return a string representing the current version of grpc.
Definition: version.cc:26
GRPCAPI grpc_call * grpc_channel_create_call(grpc_channel *channel, grpc_call *parent_call, uint32_t propagation_mask, grpc_completion_queue *completion_queue, grpc_slice method, const grpc_slice *host, gpr_timespec deadline, void *reserved)
Create a call given a grpc_channel, in order to call 'method'.
Definition: channel.cc:378
GRPCAPI char * grpc_call_get_peer(grpc_call *call)
Returns a newly allocated string representing the endpoint to which this call is communicating with.
Definition: call.cc:657
GRPCAPI void grpc_server_destroy(grpc_server *server)
Destroy a server.
Definition: server.cc:1545
GRPCAPI char * grpc_channelz_get_socket(intptr_t socket_id)
Definition: channelz_registry.cc:270
GRPCAPI grpc_completion_queue * grpc_completion_queue_create(const grpc_completion_queue_factory *factory, const grpc_completion_queue_attributes *attributes, void *reserved)
Create a completion queue.
Definition: completion_queue_factory.cc:82
GRPCAPI const grpc_completion_queue_factory * grpc_completion_queue_factory_lookup(const grpc_completion_queue_attributes *attributes)
Returns the completion queue factory based on the attributes.
Definition: completion_queue_factory.cc:46
GRPCAPI int grpc_completion_queue_thread_local_cache_flush(grpc_completion_queue *cq, void **tag, int *ok)
Flushes the thread local cache for cq.
Definition: completion_queue.cc:455
GRPCAPI char * grpc_channel_get_target(grpc_channel *channel)
Return a newly allocated string representing the target a channel was created for.
Definition: channel.cc:319
grpc_server_register_method_payload_handling
How to handle payloads for a registered method.
Definition: grpc.h:366
@ GRPC_SRM_PAYLOAD_NONE
Don't try to read the payload.
Definition: grpc.h:368
@ GRPC_SRM_PAYLOAD_READ_INITIAL_BYTE_BUFFER
Read the initial payload as a byte buffer.
Definition: grpc.h:370
GRPCAPI struct census_context * grpc_census_call_get_context(grpc_call *call)
Retrieve the calls current census context.
Definition: grpc_context.cc:34
GRPCAPI grpc_resource_quota * grpc_resource_quota_create(const char *trace_name)
Create a buffer pool.
Definition: resource_quota.cc:646
GRPCAPI char * grpc_channelz_get_server(intptr_t server_id)
Definition: channelz_registry.cc:199
GRPCAPI void grpc_server_start(grpc_server *server)
Start a server - tells all listeners to start listening.
Definition: server.cc:1523
GRPCAPI grpc_server * grpc_server_create(const grpc_channel_args *args, void *reserved)
Create a server.
Definition: server.cc:1484
GRPCAPI grpc_event grpc_completion_queue_next(grpc_completion_queue *cq, gpr_timespec deadline, void *reserved)
Blocks until an event is available, the completion queue is being shut down, or deadline is reached.
Definition: completion_queue.cc:1133
GRPCAPI void grpc_resource_quota_ref(grpc_resource_quota *resource_quota)
Add a reference to a buffer pool.
Definition: resource_quota.cc:699
GRPCAPI grpc_channel * grpc_lame_client_channel_create(const char *target, grpc_status_code error_code, const char *error_message)
Create a lame client: this client fails every operation attempted on it.
Definition: lame_client.cc:164
GRPCAPI char * grpc_channelz_get_channel(intptr_t channel_id)
Definition: channelz_registry.cc:236
GRPCAPI void * grpc_call_arena_alloc(grpc_call *call, size_t size)
Allocate memory in the grpc_call arena: this memory is automatically discarded at call completion.
Definition: call.cc:312
GRPCAPI int grpc_channel_num_external_connectivity_watchers(grpc_channel *channel)
Number of active "external connectivity state watchers" attached to a channel.
Definition: channel_connectivity.cc:47
GRPCAPI int grpc_header_nonbin_value_is_legal(grpc_slice slice)
Check whether a non-binary metadata value is legal (will be accepted by core)
Definition: validate_metadata.cc:94
GRPCAPI void grpc_shutdown_blocking(void)
DEPRECATED.
Definition: init.cc:241
GRPCAPI void grpc_call_details_destroy(grpc_call_details *details)
Definition: call_details.cc:36
GRPCAPI grpc_call_error grpc_server_request_call(grpc_server *server, grpc_call **call, grpc_call_details *details, grpc_metadata_array *request_metadata, grpc_completion_queue *cq_bound_to_call, grpc_completion_queue *cq_for_notification, void *tag_new)
Request notification of a new call.
Definition: server.cc:1552
GRPCAPI void grpc_call_unref(grpc_call *call)
Unref a call.
Definition: call.cc:581
GRPCAPI grpc_call_error grpc_call_cancel(grpc_call *call, void *reserved)
Error handling for grpc_call Most grpc_call functions return a grpc_error.
Definition: call.cc:623
GRPCAPI void grpc_server_cancel_all_calls(grpc_server *server)
Cancel all in-progress calls.
Definition: server.cc:1538
GRPCAPI void grpc_completion_queue_thread_local_cache_init(grpc_completion_queue *cq)
Initializes a thread local cache for cq.
Definition: completion_queue.cc:447
GRPCAPI int grpc_tracer_set_enabled(const char *name, int enabled)
Enable or disable a tracer.
Definition: trace.cc:152
GRPCAPI grpc_call * grpc_channel_create_registered_call(grpc_channel *channel, grpc_call *parent_call, uint32_t propagation_mask, grpc_completion_queue *completion_queue, void *registered_call_handle, gpr_timespec deadline, void *reserved)
Create a call given a handle returned from grpc_channel_register_call.
Definition: channel.cc:472
GRPCAPI grpc_completion_queue * grpc_completion_queue_create_for_pluck(void *reserved)
Helper function to create a completion queue with grpc_cq_completion_type of GRPC_CQ_PLUCK and grpc_c...
Definition: completion_queue_factory.cc:67
GRPCAPI void grpc_resource_quota_resize(grpc_resource_quota *resource_quota, size_t new_size)
Update the size of a buffer pool.
Definition: resource_quota.cc:720
GRPCAPI void * grpc_channel_register_call(grpc_channel *channel, const char *method, const char *host, void *reserved)
Pre-register a method/host pair on a channel.
Definition: channel.cc:450
GRPCAPI grpc_channel * grpc_insecure_channel_create(const char *target, const grpc_channel_args *args, void *reserved)
Create a client channel to 'target'.
Definition: channel_create.cc:95
GRPCAPI void grpc_completion_queue_destroy(grpc_completion_queue *cq)
Destroy a completion queue.
Definition: completion_queue.cc:1423
GRPCAPI void grpc_channel_get_info(grpc_channel *channel, const grpc_channel_info *channel_info)
Request info about the channel.
Definition: channel.cc:324
GRPCAPI void grpc_census_call_set_context(grpc_call *call, struct census_context *context)
Set census context for a call; Must be called before first call to grpc_call_start_batch().
Definition: grpc_context.cc:26
GRPCAPI void grpc_register_plugin(void(*init)(void), void(*destroy)(void))
Registers a plugin to be initialized and destroyed with the library.
Definition: init.cc:119
GRPCAPI void grpc_call_details_init(grpc_call_details *details)
Definition: call_details.cc:30
GRPCAPI void * grpc_server_register_method(grpc_server *server, const char *method, const char *host, grpc_server_register_method_payload_handling payload_handling, uint32_t flags)
Registers a method in the server.
Definition: server.cc:1511
GRPCAPI char * grpc_channelz_get_top_channels(intptr_t start_channel_id)
Channelz is under active development.
Definition: channelz_registry.cc:183
GRPCAPI const char * grpc_call_error_to_string(grpc_call_error error)
Convert grpc_call_error values to a string.
Definition: call.cc:2037
GRPCAPI void grpc_resource_quota_set_max_threads(grpc_resource_quota *resource_quota, int new_max_threads)
Update the size of the maximum number of threads allowed.
Definition: resource_quota.cc:711
grpc_call_error
Result of a grpc call.
Definition: grpc_types.h:441
#define GRPCAPI
Definition: port_platform.h:562
grpc_status_code
Definition: status.h:26
grpc_connectivity_state
Connectivity state of a channel.
Definition: connectivity_state.h:27
grpc_error_handle error
Definition: lame_client.cc:54
grpc_slice slice
Definition: server.cc:461
Analogous to struct timespec.
Definition: gpr_types.h:47
Definition: grpc_types.h:85
Definition: grpc_types.h:40
Definition: grpc_types.h:569
Definition: call.cc:139
An array of arguments that can be passed around.
Definition: grpc_types.h:132
Information requested from the channel.
Definition: grpc_types.h:704
Definition: channel.h:105
Definition: grpc_types.h:778
Definition: completion_queue_factory.h:32
Specifies an interface class to be used as a tag for callback-based completion queues.
Definition: grpc_types.h:757
Definition: completion_queue.cc:339
The result of an operation.
Definition: grpc_types.h:548
Definition: grpc_types.h:563
Operation data: one field for each op type (except SEND_CLOSE_FROM_CLIENT which has no arguments)
Definition: grpc_types.h:624
Definition: resource_quota.cc:127
Definition: server.h:460
Definition: grpc.h:415
void * user_data
Definition: grpc.h:419
Definition: server.h:450
A grpc_slice s, if initialized, represents the byte range s.bytes[0..s.length-1].
Definition: slice.h:60
Definition: call.cc:118