GRPC C++  1.26.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 
92 
94 GRPCAPI const char* grpc_version_string(void);
95 
97 GRPCAPI const char* grpc_g_stands_for(void);
98 
103  const grpc_completion_queue_attributes* attributes);
104 
108  void* reserved);
109 
113  void* reserved);
114 
120  void* reserved);
121 
124  const grpc_completion_queue_factory* factory,
125  const grpc_completion_queue_attributes* attributes, void* reserved);
126 
136  gpr_timespec deadline,
137  void* reserved);
138 
151  void* tag, gpr_timespec deadline,
152  void* reserved);
153 
156 #define GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 6
157 
166 
170 
171 /*********** EXPERIMENTAL API ************/
178 
179 /*********** EXPERIMENTAL API ************/
186  grpc_completion_queue* cq, void** tag, int* ok);
187 
190  grpc_channel* channel, int try_to_connect);
191 
196  grpc_channel* channel);
197 
204  grpc_channel* channel, grpc_connectivity_state last_observed_state,
205  gpr_timespec deadline, grpc_completion_queue* cq, void* tag);
206 
209 
218  grpc_channel* channel, grpc_call* parent_call, uint32_t propagation_mask,
219  grpc_completion_queue* completion_queue, grpc_slice method,
220  const grpc_slice* host, gpr_timespec deadline, void* reserved);
221 
225  void* tag, void* reserved);
226 
231  const char* method, const char* host,
232  void* reserved);
233 
237  grpc_channel* channel, grpc_call* parent_call, uint32_t propagation_mask,
238  grpc_completion_queue* completion_queue, void* registered_call_handle,
239  gpr_timespec deadline, void* reserved);
240 
243 GRPCAPI void* grpc_call_arena_alloc(grpc_call* call, size_t size);
244 
266  const grpc_op* ops, size_t nops,
267  void* tag, void* reserved);
268 
278 
279 struct census_context;
280 
284  struct census_context* context);
285 
287 GRPCAPI struct census_context* grpc_census_call_get_context(grpc_call* call);
288 
292 
298  const grpc_channel_info* channel_info);
299 
304 
313  const char* target, const grpc_channel_args* args, void* reserved);
314 
317  const char* target, grpc_status_code error_code, const char* error_message);
318 
321 
333 GRPCAPI grpc_call_error grpc_call_cancel(grpc_call* call, void* reserved);
334 
346  grpc_status_code status,
347  const char* description,
348  void* reserved);
349 
352 GRPCAPI void grpc_call_ref(grpc_call* call);
353 
356 GRPCAPI void grpc_call_unref(grpc_call* call);
357 
367  grpc_server* server, grpc_call** call, grpc_call_details* details,
368  grpc_metadata_array* request_metadata,
369  grpc_completion_queue* cq_bound_to_call,
370  grpc_completion_queue* cq_for_notification, void* tag_new);
371 
373 typedef enum {
379 
388  grpc_server* server, const char* method, const char* host,
389  grpc_server_register_method_payload_handling payload_handling,
390  uint32_t flags);
391 
396  grpc_server* server, void* registered_method, grpc_call** call,
397  gpr_timespec* deadline, grpc_metadata_array* request_metadata,
398  grpc_byte_buffer** optional_payload,
399  grpc_completion_queue* cq_bound_to_call,
400  grpc_completion_queue* cq_for_notification, void* tag_new);
401 
410  void* reserved);
411 
418  void* reserved);
419 
424  const char* addr);
425 
428 
438  void* tag);
439 
443 
449 
458 GRPCAPI int grpc_tracer_set_enabled(const char* name, int enabled);
459 
462 
466 
469 
472 
475 
478 
481 
484  size_t new_size);
485 
488  grpc_resource_quota* resource_quota, int new_max_threads);
489 
493 
494 /************* CHANNELZ API *************/
508 /* Gets all root channels (i.e. channels the application has directly
509  created). This does not include subchannels nor non-top level channels.
510  The returned string is allocated and must be freed by the application. */
511 GRPCAPI char* grpc_channelz_get_top_channels(intptr_t start_channel_id);
512 
513 /* Gets all servers that exist in the process. */
514 GRPCAPI char* grpc_channelz_get_servers(intptr_t start_server_id);
515 
516 /* Returns a single Server, or else a NOT_FOUND code. */
517 GRPCAPI char* grpc_channelz_get_server(intptr_t server_id);
518 
519 /* Gets all server sockets that exist in the server. */
520 GRPCAPI char* grpc_channelz_get_server_sockets(intptr_t server_id,
521  intptr_t start_socket_id,
522  intptr_t max_results);
523 
524 /* Returns a single Channel, or else a NOT_FOUND code. The returned string
525  is allocated and must be freed by the application. */
526 GRPCAPI char* grpc_channelz_get_channel(intptr_t channel_id);
527 
528 /* Returns a single Subchannel, or else a NOT_FOUND code. The returned string
529  is allocated and must be freed by the application. */
530 GRPCAPI char* grpc_channelz_get_subchannel(intptr_t subchannel_id);
531 
532 /* Returns a single Socket, or else a NOT_FOUND code. The returned string
533  is allocated and must be freed by the application. */
534 GRPCAPI char* grpc_channelz_get_socket(intptr_t socket_id);
535 
536 #ifdef __cplusplus
537 }
538 #endif
539 
540 #endif /* GRPC_GRPC_H */
struct grpc_call grpc_call
A Call represents an RPC.
Definition: grpc_types.h:70
GRPCAPI grpc_call_error grpc_call_cancel_with_status(grpc_call *call, grpc_status_code status, const char *description, void *reserved)
Cancel an RPC.
GRPCAPI void grpc_server_shutdown_and_notify(grpc_server *server, grpc_completion_queue *cq, void *tag)
Begin shutting down a server.
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...
grpc_status_code
Definition: status.h:26
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...
struct grpc_completion_queue_factory grpc_completion_queue_factory
The completion queue factory structure is opaque to the callers of grpc.
Definition: grpc_types.h:762
An array of arguments that can be passed around.
Definition: grpc_types.h:132
Definition: grpc_types.h:85
Read the initial payload as a byte buffer.
Definition: grpc.h:377
struct grpc_channel grpc_channel
The Channel interface allows creation of Call objects.
Definition: grpc_types.h:62
grpc_server_register_method_payload_handling
How to handle payloads for a registered method.
Definition: grpc.h:373
GRPCAPI void grpc_server_register_completion_queue(grpc_server *server, grpc_completion_queue *cq, void *reserved)
Register a completion queue with the server.
GRPCAPI const char * grpc_g_stands_for(void)
Return a string specifying what the &#39;g&#39; in gRPC stands for.
GRPCAPI int grpc_is_initialized(void)
EXPERIMENTAL.
GRPCAPI const char * grpc_version_string(void)
Return a string representing the current version of grpc.
The result of an operation.
Definition: grpc_types.h:514
GRPCAPI void grpc_channel_ping(grpc_channel *channel, grpc_completion_queue *cq, void *tag, void *reserved)
Ping the channels peer (load balanced channels will select one sub-channel to ping); if the channel i...
GRPCAPI int grpc_channel_num_external_connectivity_watchers(grpc_channel *channel)
Number of active "external connectivity state watchers" attached to a channel.
A grpc_slice s, if initialized, represents the byte range s.bytes[0..s.length-1]. ...
Definition: slice.h:60
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.
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.
GRPCAPI void grpc_call_details_destroy(grpc_call_details *details)
GRPCAPI void grpc_resource_quota_unref(grpc_resource_quota *resource_quota)
Drop a reference to a buffer pool.
GRPCAPI void grpc_server_start(grpc_server *server)
Start a server - tells all listeners to start listening.
struct grpc_server grpc_server
A server listens to some port and responds to request calls.
Definition: grpc_types.h:65
GRPCAPI char * grpc_channelz_get_top_channels(intptr_t start_channel_id)
Channelz is under active development.
GRPCAPI char * grpc_channelz_get_subchannel(intptr_t subchannel_id)
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: grpc_types.h:535
Definition: grpc_types.h:40
Don&#39;t try to read the payload.
Definition: grpc.h:375
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.
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: grpc_types.h:529
GRPCAPI void grpc_server_cancel_all_calls(grpc_server *server)
Cancel all in-progress calls.
GRPCAPI char * grpc_channelz_get_server(intptr_t server_id)
GRPCAPI grpc_connectivity_state grpc_channel_check_connectivity_state(grpc_channel *channel, int try_to_connect)
Check the connectivity state of a channel.
Definition: grpc_types.h:742
grpc_call_error
Result of a grpc call.
Definition: grpc_types.h:407
GRPCAPI char * grpc_channel_get_target(grpc_channel *channel)
Return a newly allocated string representing the target a channel was created for.
GRPCAPI int grpc_is_binary_header(grpc_slice slice)
Check whether a metadata key corresponds to a binary value.
GRPCAPI char * grpc_channelz_get_channel(intptr_t channel_id)
GRPCAPI void grpc_channel_reset_connect_backoff(grpc_channel *channel)
EXPERIMENTAL.
grpc_connectivity_state
Connectivity state of a channel.
Definition: connectivity_state.h:27
GRPCAPI void grpc_channel_get_info(grpc_channel *channel, const grpc_channel_info *channel_info)
Request info about the channel.
GRPCAPI grpc_completion_queue * grpc_completion_queue_create_for_callback(grpc_experimental_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...
GRPCAPI void grpc_call_details_init(grpc_call_details *details)
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.
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.
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.
GRPCAPI void grpc_resource_quota_ref(grpc_resource_quota *resource_quota)
Add a reference to a buffer pool.
GRPCAPI void grpc_server_destroy(grpc_server *server)
Destroy a server.
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 &#39;method&#39;.
GRPCAPI void grpc_metadata_array_init(grpc_metadata_array *array)
GRPCAPI struct census_context * grpc_census_call_get_context(grpc_call *call)
Retrieve the calls current census context.
GRPCAPI void grpc_completion_queue_destroy(grpc_completion_queue *cq)
Destroy a completion queue.
GRPCAPI grpc_resource_quota * grpc_resource_quota_create(const char *trace_name)
Create a buffer pool.
GRPCAPI void grpc_channel_destroy(grpc_channel *channel)
Close and destroy a grpc channel.
Operation data: one field for each op type (except SEND_CLOSE_FROM_CLIENT which has no arguments) ...
Definition: grpc_types.h:590
GRPCAPI int grpc_server_add_insecure_http2_port(grpc_server *server, const char *addr)
Add a HTTP2 over plaintext over tcp listener.
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.
GRPCAPI void grpc_completion_queue_shutdown(grpc_completion_queue *cq)
Begin destruction of a completion queue.
GRPCAPI char * grpc_channelz_get_servers(intptr_t start_server_id)
GRPCAPI void grpc_init(void)
Initialize the grpc library.
GRPCAPI void grpc_shutdown_blocking(void)
EXPERIMENTAL.
#define GRPCAPI
Definition: port_platform.h:608
GRPCAPI void grpc_metadata_array_destroy(grpc_metadata_array *array)
GRPCAPI grpc_channel * grpc_insecure_channel_create(const char *target, const grpc_channel_args *args, void *reserved)
Create a client channel to &#39;target&#39;.
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 &#39;tag&#39; ...
GRPCAPI void grpc_shutdown(void)
Shut down the grpc library.
GRPCAPI void grpc_call_ref(grpc_call *call)
Ref a call.
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.
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.
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...
GRPCAPI grpc_server * grpc_server_create(const grpc_channel_args *args, void *reserved)
Create a server.
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)
Information requested from the channel.
Definition: grpc_types.h:668
GRPCAPI void grpc_call_unref(grpc_call *call)
Unref a call.
GRPCAPI int grpc_header_key_is_legal(grpc_slice slice)
Check whether a metadata key is legal (will be accepted by core)
struct grpc_resource_quota grpc_resource_quota
Definition: grpc_types.h:677
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.
Analogous to struct timespec.
Definition: gpr_types.h:47
GRPCAPI grpc_event grpc_completion_queue_pluck(grpc_completion_queue *cq, void *tag, gpr_timespec deadline, void *reserved)
Blocks until an event with tag &#39;tag&#39; is available, the completion queue is being shutdown or deadline...
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().
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...
GRPCAPI void grpc_completion_queue_thread_local_cache_init(grpc_completion_queue *cq)
Initializes a thread local cache for cq.
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.
struct grpc_completion_queue grpc_completion_queue
Completion Queues enable notification of the completion of asynchronous actions.
Definition: grpc_types.h:56
GRPCAPI char * grpc_channelz_get_server_sockets(intptr_t server_id, intptr_t start_socket_id, intptr_t max_results)
EXPERIMENTAL: Specifies an interface class to be used as a tag for callback-based completion queues...
Definition: grpc_types.h:722
GRPCAPI int grpc_completion_queue_thread_local_cache_flush(grpc_completion_queue *cq, void **tag, int *ok)
Flushes the thread local cache for cq.
GRPCAPI int grpc_tracer_set_enabled(const char *name, int enabled)
Enable or disable a tracer.
GRPCAPI void grpc_register_plugin(void(*init)(void), void(*destroy)(void))
Registers a plugin to be initialized and destroyed with the library.
GRPCAPI void grpc_resource_quota_resize(grpc_resource_quota *resource_quota, size_t new_size)
Update the size of a buffer pool.
GRPCAPI const char * grpc_call_error_to_string(grpc_call_error error)
Convert grpc_call_error values to a string.
GRPCAPI int grpc_channel_support_connectivity_watcher(grpc_channel *channel)
Check whether a grpc channel supports connectivity watcher.
GRPCAPI char * grpc_channelz_get_socket(intptr_t socket_id)