GRPC Core  9.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 
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 
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 
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 
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,
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 */
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:658
GRPCAPI void grpc_server_shutdown_and_notify(grpc_server *server, grpc_completion_queue *cq, void *tag)
Begin shutting down a server.
Definition: server.cc:1290
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_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:1112
An array of arguments that can be passed around.
Definition: grpc_types.h:132
Definition: channel.h:66
Definition: grpc_types.h:85
Read the initial payload as a byte buffer.
Definition: grpc.h:377
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.
Definition: server.cc:988
GRPCAPI const char * grpc_g_stands_for(void)
Return a string specifying what the &#39;g&#39; in gRPC stands for.
Definition: version.cc:28
GRPCAPI int grpc_is_initialized(void)
EXPERIMENTAL.
Definition: init.cc:235
grpc_linked_mdelem status
Definition: lame_client.cc:44
GRPCAPI const char * grpc_version_string(void)
Return a string representing the current version of grpc.
Definition: version.cc:26
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...
Definition: channel_ping.cc:48
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:189
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.
Definition: completion_queue_factory.cc:83
grpc_status_code error_code
Definition: lame_client.cc:52
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:609
GRPCAPI void grpc_call_details_destroy(grpc_call_details *details)
Definition: call_details.cc:36
GRPCAPI void grpc_resource_quota_unref(grpc_resource_quota *resource_quota)
Drop a reference to a buffer pool.
Definition: resource_quota.cc:685
grpc_connectivity_state
Connectivity state of a channel.
Definition: connectivity_state.h:27
GRPCAPI void grpc_server_start(grpc_server *server)
Start a server - tells all listeners to start listening.
Definition: server.cc:1096
GRPCAPI char * grpc_channelz_get_top_channels(intptr_t start_channel_id)
Channelz is under active development.
Definition: channelz_registry.cc:195
GRPCAPI char * grpc_channelz_get_subchannel(intptr_t subchannel_id)
Definition: channelz_registry.cc:258
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:766
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.
Definition: server.cc:1467
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:642
Definition: grpc_types.h:529
Definition: call.cc:113
GRPCAPI void grpc_server_cancel_all_calls(grpc_server *server)
Cancel all in-progress calls.
Definition: server.cc:1364
GRPCAPI char * grpc_channelz_get_server(intptr_t server_id)
Definition: channelz_registry.cc:204
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:33
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.
Definition: channel.cc:332
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 char * grpc_channelz_get_channel(intptr_t channel_id)
Definition: channelz_registry.cc:238
GRPCAPI void grpc_channel_reset_connect_backoff(grpc_channel *channel)
EXPERIMENTAL.
Definition: channel.cc:345
GRPCAPI void grpc_channel_get_info(grpc_channel *channel, const grpc_channel_info *channel_info)
Request info about the channel.
Definition: channel.cc:337
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...
Definition: completion_queue_factory.cc:74
Definition: completion_queue_factory.h:32
GRPCAPI void grpc_call_details_init(grpc_call_details *details)
Definition: call_details.cc:30
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:173
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:1060
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:444
GRPCAPI void grpc_resource_quota_ref(grpc_resource_quota *resource_quota)
Add a reference to a buffer pool.
Definition: resource_quota.cc:697
GRPCAPI void grpc_server_destroy(grpc_server *server)
Destroy a server.
Definition: server.cc:1380
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;.
Definition: channel.cc:389
GRPCAPI void grpc_metadata_array_init(grpc_metadata_array *array)
Definition: metadata_array.cc:28
GRPCAPI struct census_context * grpc_census_call_get_context(grpc_call *call)
Retrieve the calls current census context.
Definition: grpc_context.cc:34
const char * error_message
Definition: lame_client.cc:53
GRPCAPI void grpc_completion_queue_destroy(grpc_completion_queue *cq)
Destroy a completion queue.
Definition: completion_queue.cc:1402
GRPCAPI grpc_resource_quota * grpc_resource_quota_create(const char *trace_name)
Create a buffer pool.
Definition: resource_quota.cc:642
GRPCAPI void grpc_channel_destroy(grpc_channel *channel)
Close and destroy a grpc channel.
Definition: channel.cc:518
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.
Definition: server_chttp2.cc:30
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 void grpc_completion_queue_shutdown(grpc_completion_queue *cq)
Begin destruction of a completion queue.
Definition: completion_queue.cc:1394
GRPCAPI char * grpc_channelz_get_servers(intptr_t start_server_id)
Definition: channelz_registry.cc:200
Definition: completion_queue.cc:321
GRPCAPI void grpc_init(void)
Initialize the grpc library.
Definition: init.cc:125
GRPCAPI void grpc_shutdown_blocking(void)
EXPERIMENTAL.
Definition: init.cc:226
#define GRPCAPI
Definition: port_platform.h:608
GRPCAPI void grpc_metadata_array_destroy(grpc_metadata_array *array)
Definition: metadata_array.cc:33
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;.
Definition: channel_create.cc:90
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; ...
Definition: call.cc:1960
GRPCAPI void grpc_shutdown(void)
Shut down the grpc library.
Definition: init.cc:211
GRPCAPI void grpc_call_ref(grpc_call *call)
Ref a call.
Definition: call.cc:562
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:215
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:420
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:299
GRPCAPI grpc_server * grpc_server_create(const grpc_channel_args *args, void *reserved)
Create a server.
Definition: server.cc:1008
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
Information requested from the channel.
Definition: grpc_types.h:668
GRPCAPI void grpc_call_unref(grpc_call *call)
Unref a call.
Definition: call.cc:564
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 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:709
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...
Definition: completion_queue.cc:1306
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 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_completion_queue_thread_local_cache_init(grpc_completion_queue *cq)
Initializes a thread local cache for cq.
Definition: completion_queue.cc:430
Definition: resource_quota.cc:125
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:1515
GRPCAPI char * grpc_channelz_get_server_sockets(intptr_t server_id, intptr_t start_socket_id, intptr_t max_results)
Definition: channelz_registry.cc:222
grpc_status_code
Definition: status.h:26
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.
Definition: completion_queue.cc:437
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:116
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:718
Definition: call.cc:134
GRPCAPI const char * grpc_call_error_to_string(grpc_call_error error)
Convert grpc_call_error values to a string.
Definition: call.cc:2009
GRPCAPI int grpc_channel_support_connectivity_watcher(grpc_channel *channel)
Check whether a grpc channel supports connectivity watcher.
Definition: channel_connectivity.cc:209
GRPCAPI char * grpc_channelz_get_socket(intptr_t socket_id)
Definition: channelz_registry.cc:276
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 int grpc_tracer_set_enabled(const char *name, int enabled)
Enable or disable a tracer.
Definition: trace.cc:152
Definition: server.cc:222
grpc_linked_mdelem details
Definition: lame_client.cc:45