Specifies an interface class to be used as a tag for callback-based
completion queues. This can be used directly, as the first element of a
struct in C, or as a base class in C++. Its “run” value should be assigned to
some non-member function, such as a static method.
The default message compression algorithm. It’ll be used in the absence of
call specific settings. This option corresponds to the channel argument key
behind \a GRPC_COMPRESSION_CHANNEL_DEFAULT_ALGORITHM.
The default compression level. It’ll be used in the absence of call
specific settings. This option corresponds to the channel
argument key behind \a GRPC_COMPRESSION_CHANNEL_DEFAULT_LEVEL. If present,
takes precedence over \a default_algorithm.
TODO(dgq): currently only available for server channels.
grpc_metadata_credentials plugin is an API user provided structure used to
create grpc_credentials objects that can be set on a channel (composed) or
a call. See grpc_credentials_metadata_create_from_plugin below.
The grpc client stack will call the get_metadata method of the plugin for
every call in scope for the credentials created from it.
ownership of the array is with the caller, but ownership of the elements
stays with the call object (ie key, value members are owned by the call
object, recv_initial_metadata->array is owned by the caller).
After the operation completes, call grpc_metadata_array_destroy on this
value, or reuse it in a future op.
ownership of the byte buffer is moved to the caller; the caller must
call grpc_byte_buffer_destroy on this value, or reuse it in a future op.
The returned byte buffer will be NULL if trailing metadata was
received instead of a message.
Options for creating STS Oauth Token Exchange credentials following the IETF
draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
Optional fields may be set to NULL or empty string. It is the responsibility
of the caller to ensure that the subject and actor tokens are refreshed on
disk at the specified paths. This API is used for experimental purposes for
now and may change in the future.
Deprecated in favor of grpc_ssl_verify_peer_options. It will be removed
after all of its call sites are migrated to grpc_ssl_verify_peer_options.
Object that holds additional peer-verification options on a secure
channel.
Result of a grpc call. If the caller satisfies the prerequisites of a
particular operation, the grpc_call_error returned will be GRPC_CALL_OK.
Receiving any other value listed here is an indication of a bug in the
caller.
Compression levels allow a party with knowledge of its peer’s accepted
encodings to request compression in an abstract way. The level-algorithm
mapping is performed internally and depends on the peer’s supported
compression algorithms.
Completion queues internally MAY maintain a set of file descriptors in a
structure called ‘pollset’. This enum specifies if a completion queue has an
associated pollset and any restrictions on the type of file descriptors that
can be present in the pollset.
Return the CPU on which the current thread is executing; N.B. This should
be considered advisory only - it is possible that the thread is switched
to a different CPU at any time. Returns a value in range
[0, gpr_cpu_num_cores() - 1]
Return the value set by gpr_event_set(ev, …), or NULL if no such call has
completed. If the result is non-NULL, all operations that occurred prior to
the gpr_event_set(ev, …) set will be visible after this call returns.
Requires: *ev initialized. This operation is faster than acquiring a mutex
on most platforms.
Set *ev so that gpr_event_get() and gpr_event_wait() will return value.
Requires: *ev initialized; value != NULL; no prior or concurrent calls to
gpr_event_set(ev, …) since initialization.
Wait until *ev is set by gpr_event_set(ev, …), or abs_deadline is
exceeded, then return gpr_event_get(ev). Requires: *ev initialized. Use
abs_deadline==gpr_inf_future for no deadline. When the event has been
signalled before the call, this operation is faster than acquiring a mutex
on most platforms.
Returns a string allocated with gpr_malloc that contains a UTF-8
formatted error message, corresponding to the error messageid.
Use in conjunction with GetLastError() et al.
malloc.
If size==0, always returns NULL. Otherwise this function never returns NULL.
The pointer returned is suitably aligned for any kind of variable it could
contain.
This method adds a target service account to grpc client’s ALTS credentials
options instance. It is used for experimental purpose for now and subject
to change.
This method creates an ALTS channel credential object. The security
level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
It is used for experimental purpose for now and subject to change.
This method destroys a grpc_alts_credentials_options instance by
de-allocating all of its occupied memory. It is used for experimental purpose
for now and subject to change.
EXPERIMENTAL - Subject to change.
Releases grpc_authorization_policy_provider object. The creator of
grpc_authorization_policy_provider is responsible for its release.
Cancel an RPC.
Can be called multiple times, from any thread.
THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status
are thread-safe, and can be called at any point before grpc_call_unref
is called.
Cancel an RPC.
Can be called multiple times, from any thread.
If a status has not been received for the call, set it to the status code
and description passed in.
Importantly, this function does not send status nor description to the
remote endpoint.
Note that \a description doesn’t need be a static string.
It doesn’t need to be alive after the call to
grpc_call_cancel_with_status completes.
Returns a newly allocated string representing the endpoint to which this
call is communicating with. The string is in the uri format accepted by
grpc_channel_create.
The returned string should be disposed of with gpr_free().
Start a batch of operations defined in the array ops; when complete, post a
completion of type ‘tag’ to the completion queue bound to the call.
The order of ops specified in the batch has no significance.
Only one operation of each type can be active at once in any given
batch.
If a call to grpc_call_start_batch returns GRPC_CALL_OK you must call
grpc_completion_queue_next or grpc_completion_queue_pluck on the completion
queue associated with ‘call’ for work to be performed. If a call to
grpc_call_start_batch returns any value other than GRPC_CALL_OK it is
guaranteed that no state associated with ‘call’ is changed and it is not
appropriate to call grpc_completion_queue_next or
grpc_completion_queue_pluck consequent to the failed grpc_call_start_batch
call.
If a call to grpc_call_start_batch with an empty batch returns
GRPC_CALL_OK, the tag is put in the completion queue immediately.
THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment
needs to be synchronized. As an optimization, you may synchronize batches
containing just send operations independently from batches containing just
receive operations. Access to grpc_call_start_batch with an empty batch is
thread-compatible.
Creates a secure channel using the passed-in credentials. Additional
channel level configuration MAY be provided by grpc_channel_args, though
the expectation is that most clients will want to simply pass NULL. The
user data in ‘args’ need only live through the invocation of this function.
However, if any args of the ‘pointer’ type are passed, then the referenced
vtable must be maintained by the caller until grpc_channel_destroy
terminates. See grpc_channel_args definition for more on this.
Create a call given a grpc_channel, in order to call ‘method’. All
completions are sent to ‘completion_queue’. ‘method’ and ‘host’ need only
live through the invocation of this function.
If parent_call is non-NULL, it must be a server-side call. It will be used
to propagate properties from the server call to this new client call,
depending on the value of \a propagation_mask (see propagation_bits.h for
possible values).
Create a secure channel to ‘target’ using file descriptor ‘fd’ and passed-in
credentials. The ‘target’ argument will be used to indicate the name for
this channel. Note that this API currently only supports insecure channel
credentials. Using other types of credentials will result in a failure.
Request info about the channel.
\a channel_info indicates what information is being requested and
how that information will be returned.
\a channel_info is owned by the caller.
EXPERIMENTAL. Resets the channel’s connect backoff.
TODO(roth): When we see whether this proves useful, either promote
to non-experimental or remove it.
Watch for a change in connectivity state.
Once the channel connectivity state is different from last_observed_state,
tag will be enqueued on cq with success=1.
If deadline expires BEFORE the state is changed, tag will be enqueued on cq
with success=0.
CHANNELZ API *************/
churn as the feature is implemented. This comment will be removed once
channelz is officially supported, and these APIs become stable. For now
you may track the progress by following this github issue:
https://github.com/grpc/grpc/issues/15340
Helper function to create a completion queue with grpc_cq_completion_type
of GRPC_CQ_CALLBACK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING.
This function is experimental.
Begin destruction of a completion queue. Once all possible events are
drained then grpc_completion_queue_next will start to produce
GRPC_QUEUE_SHUTDOWN events only. At that point it’s safe to call
grpc_completion_queue_destroy.
EXPERIMENTAL API ************/
Returns 1 if there was contents in the cache. If there was an event
in \a cq tls cache, its tag is placed in tag, and ok is set to the
event success.
Updates \a name with the encoding name corresponding to a valid \a
algorithm. Note that \a name is statically allocated and must not be freed.
Returns 1 upon success, 0 otherwise.
Creates a compute engine credentials object for connecting to Google.
WARNING: Do NOT use this credentials to connect to a non-google service as
this could result in an oauth2 token leak.
Creates default credentials to connect to a google gRPC service.
WARNING: Do NOT use this credentials to connect to a non-google service as
this could result in an oauth2 token leak. The security level of the
resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
Creates an Oauth2 Refresh Token credentials object for connecting to Google.
May return NULL if the input is invalid.
WARNING: Do NOT use this credentials to connect to a non-google service as
this could result in an oauth2 token leak.
EXPERIMENTAL. Returns 1 if the grpc library has been initialized.
TODO(ericgribkoff) Decide if this should be promoted to non-experimental as
part of stabilizing the fork support API, as tracked in
https://github.com/grpc/grpc/issues/15334
This method creates a local channel credential object. The security level
of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY for UDS and
GRPC_SECURITY_NONE for LOCAL_TCP. It is used for experimental purpose
for now and subject to change.
Returns a compressed RAW byte buffer instance over the given slices (up to
\a nslices). The \a compression argument defines the compression algorithm
used to generate the data in \a slices.
Add the connected secure communication channel based on file descriptor ‘fd’
to the ‘server’ and server credentials ‘creds’. The ‘fd’ must be an open file
descriptor corresponding to a connected socket. Events from the file
descriptor may come on any of the server completion queues (i.e completion
queues registered via the grpc_server_register_completion_queue API).
Note that this API currently only supports inseure server credentials
Using other types of credentials will result in a failure.
TODO(hork): add channel_args to this API to allow endpoints and transports
created in this function to participate in the resource quota feature.
Create a server. Additional configuration for each incoming channel can
be specified with args. If no additional configuration is needed, args can
be NULL. The user data in ‘args’ need only live through the invocation of
this function. However, if any args of the ‘pointer’ type are passed, then
the referenced vtable must be maintained by the caller until
grpc_server_destroy terminates. See grpc_channel_args definition for more
on this.
Destroy a server.
Shutdown must have completed beforehand (i.e. all tags generated by
grpc_server_shutdown_and_notify must have been received, and at least
one call to grpc_server_shutdown_and_notify must have been made).
Register a completion queue with the server. Must be done for any
notification completion queue that is passed to grpc_server_request_*_call
and to grpc_server_shutdown_and_notify. Must be performed prior to
grpc_server_start.
Registers a method in the server.
Methods to this (host, method) pair will not be reported by
grpc_server_request_call, but instead be reported by
grpc_server_request_registered_call when passed the appropriate
registered_method (as returned by this function).
Must be called before grpc_server_start.
Returns NULL on failure.
Request notification of a new call.
Once a call is received, a notification tagged with \a tag_new is added to
\a cq_for_notification. \a call, \a details and \a request_metadata are
updated with the appropriate call information. \a cq_bound_to_call is bound
to \a call, and batch operation notifications for that call will be posted
to \a cq_bound_to_call.
Note that \a cq_for_notification must have been registered to the server via
\a grpc_server_register_completion_queue.
Request notification of a new pre-registered call. ‘cq_for_notification’
must have been registered to the server via
grpc_server_register_completion_queue.
Begin shutting down a server.
After completion, no new calls or connections will be admitted.
Existing calls will be allowed to complete.
Send a GRPC_OP_COMPLETE event when there are no more calls being serviced.
Shutdown is idempotent, and all tags will be notified at once if multiple
grpc_server_shutdown_and_notify calls are made. ‘cq’ must have been
registered to this server via grpc_server_register_completion_queue.
Setup a callback to override the default TLS/SSL roots.
This function is not thread-safe and must be called at initialization time
before any ssl credentials are created to have the desired side effect.
If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the
callback will not be called.
Add an element to a slice buffer - takes ownership of the slice.
This function is allowed to concatenate the passed in slice to the end of
some other slice if desired by the slice buffer.
add an element to a slice buffer - takes ownership of the slice and returns
the index of the slice.
Guarantees that the slice will not be concatenated at the end of another
slice (i.e. the data for this slice will begin at the first byte of the
slice at the returned index in sb->slices)
The implementation MAY decide to concatenate data at the end of a small
slice added in this fashion.
Create a slice by copying a string.
Does not preserve null terminators.
Equivalent to:
size_t len = strlen(source);
grpc_slice slice = grpc_slice_malloc(len);
memcpy(slice->data, source, len);
Create a slice pointing at some data. Calls malloc to allocate a refcount
for the object, and arranges that destroy will be called with the pointer
passed in at destruction.
Equivalent to grpc_slice_new, but with a separate pointer that is
passed to the destroy function. This function can be useful when
the data is part of a larger structure that must be destroyed when
the data is no longer needed.
Splits s into two: modifies s to be s[split:s.length], and returns a new
slice, sharing a refcount with s, that contains s[0:split].
Requires s initialized, split <= s.length
Splits s into two: modifies s to be s[0:split], and returns a new slice,
sharing a refcount with s, that contains s[split:s.length].
Requires s initialized, split <= s.length
The same as grpc_slice_split_tail, but with an option to skip altering
refcounts (grpc_slice_split_tail_maybe_ref(…, true) is equivalent to
grpc_slice_split_tail(…))
Return a result slice derived from s, which shares a ref count with \a s,
where result.data==s.data+begin, and result.length==end-begin. The ref count
of \a s is increased by one. Do not assign result back to \a s.
Requires s initialized, begin <= end, begin <= s.length, and
end <= source->length.
Decrement the ref count of s. If the ref count of s reaches zero, all
slices sharing the ref count are destroyed, and considered no longer
initialized. If s is ultimately derived from a call to grpc_slice_new(start,
len, dest) where dest!=NULL , then (*dest)(start) is called, else if s is
ultimately derived from a call to grpc_slice_new_with_len(start, len, dest)
where dest!=NULL , then (*dest)(start, len). Requires s initialized.
Deprecated in favor of grpc_ssl_server_credentials_create_ex. It will be
removed after all of its call sites are migrated to
grpc_ssl_server_credentials_create_ex. Creates an SSL credentials object.
The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
Deprecated in favor of grpc_ssl_server_credentials_create_with_options.
Same as grpc_ssl_server_credentials_create method except uses
grpc_ssl_client_certificate_request_type enum to support more ways to
authenticate client certificates.
Creates an options object using a certificate config. Use this method when
the certificates and keys of the SSL server will not change during the
server’s lifetime.
Creates an options object using a certificate config fetcher. Use this
method to reload the certificates and keys of the SSL server without
interrupting the operation of the server. Initial certificate config will be
fetched during server initialization.
Creates an STS credentials following the STS Token Exchanged specifed in the
IETF draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
This API is used for experimental purposes for now and may change in the
future.
EXPERIMENTAL API - Subject to change.
Configures a grpc_tls_credentials_options object with tls session key
logging capability. TLS channels using these credentials have tls session
key logging enabled.
Kick call’s completion queue, it should be called after there is an event
ready to poll.
THREAD SAFETY: grpcwrap_call_kick_completion_queue is thread-safe
because it does not change the call’s state.
Callback for getting the SSL roots override from the application.
In case of success, *pem_roots_certs must be set to a NULL terminated string
containing the list of PEM encoded root certificates. The ownership is passed
to the core and freed (laster by the core) with gpr_free.
If this function fails and GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is
set to a valid path, it will override the roots specified this func