GRPC C++  1.24.0
Data Structures | Public Member Functions | Static Public Member Functions | Friends
grpc_impl::ClientContext Class Reference

A ClientContext allows the person implementing a service client to: More...

#include <client_context_impl.h>

Data Structures

class  GlobalCallbacks
 Global Callbacks. More...
 

Public Member Functions

 ClientContext ()
 
 ~ClientContext ()
 
void AddMetadata (const grpc::string &meta_key, const grpc::string &meta_value)
 Add the (meta_key, meta_value) pair to the metadata associated with a client call. More...
 
const std::multimap< grpc::string_ref, grpc::string_ref > & GetServerInitialMetadata () const
 Return a collection of initial metadata key-value pairs. More...
 
const std::multimap< grpc::string_ref, grpc::string_ref > & GetServerTrailingMetadata () const
 Return a collection of trailing metadata key-value pairs. More...
 
template<typename T >
void set_deadline (const T &deadline)
 Set the deadline for the client call. More...
 
void set_idempotent (bool idempotent)
 EXPERIMENTAL: Indicate that this request is idempotent. More...
 
void set_cacheable (bool cacheable)
 EXPERIMENTAL: Set this request to be cacheable. More...
 
void set_wait_for_ready (bool wait_for_ready)
 EXPERIMENTAL: Trigger wait-for-ready or not on this request. More...
 
void set_fail_fast (bool fail_fast)
 DEPRECATED: Use set_wait_for_ready() instead. More...
 
std::chrono::system_clock::time_point deadline () const
 Return the deadline for the client call. More...
 
gpr_timespec raw_deadline () const
 Return a gpr_timespec representation of the client call's deadline. More...
 
void set_authority (const grpc::string &authority)
 Set the per call authority header (see https://tools.ietf.org/html/rfc7540#section-8.1.2.3). More...
 
std::shared_ptr< const grpc::AuthContextauth_context () const
 Return the authentication context for this client call. More...
 
void set_credentials (const std::shared_ptr< grpc_impl::CallCredentials > &creds)
 Set credentials for the client call. More...
 
grpc_compression_algorithm compression_algorithm () const
 Return the compression algorithm the client call will request be used. More...
 
void set_compression_algorithm (grpc_compression_algorithm algorithm)
 Set algorithm to be the compression algorithm used for the client call. More...
 
void set_initial_metadata_corked (bool corked)
 Flag whether the initial metadata should be corked. More...
 
grpc::string peer () const
 Return the peer uri in a string. More...
 
void set_census_context (struct census_context *ccp)
 Get and set census context. More...
 
struct census_context * census_context () const
 
void TryCancel ()
 Send a best-effort out-of-band cancel on the call associated with this client context. More...
 
grpc_callc_call ()
 Should be used for framework-level extensions only. More...
 
grpc::string debug_error_string () const
 EXPERIMENTAL debugging API. More...
 

Static Public Member Functions

static std::unique_ptr< ClientContextFromServerContext (const grpc_impl::ServerContext &server_context, PropagationOptions options=PropagationOptions())
 Create a new ClientContext as a child of an incoming server call, according to options (. More...
 
static void SetGlobalCallbacks (GlobalCallbacks *callbacks)
 

Friends

class ::grpc::testing::InteropClientContextInspector
 
class ::grpc::internal::CallOpClientRecvStatus
 
class ::grpc::internal::CallOpRecvInitialMetadata
 
class ::grpc_impl::Channel
 
template<class R >
class ::grpc_impl::ClientReader
 
template<class W >
class ::grpc_impl::ClientWriter
 
template<class W , class R >
class ::grpc_impl::ClientReaderWriter
 
template<class R >
class ::grpc_impl::ClientAsyncReader
 
template<class W >
class ::grpc_impl::ClientAsyncWriter
 
template<class W , class R >
class ::grpc_impl::ClientAsyncReaderWriter
 
template<class R >
class ::grpc_impl::ClientAsyncResponseReader
 
template<class InputMessage , class OutputMessage >
class ::grpc::internal::BlockingUnaryCallImpl
 
template<class InputMessage , class OutputMessage >
class ::grpc_impl::internal::CallbackUnaryCallImpl
 
template<class Request , class Response >
class ::grpc_impl::internal::ClientCallbackReaderWriterImpl
 
template<class Response >
class ::grpc_impl::internal::ClientCallbackReaderImpl
 
template<class Request >
class ::grpc_impl::internal::ClientCallbackWriterImpl
 
class ::grpc_impl::internal::ClientCallbackUnaryImpl
 
class ::grpc_impl::internal::ClientContextAccessor
 

Detailed Description

A ClientContext allows the person implementing a service client to:

Context settings are only relevant to the call they are invoked with, that is to say, they aren't sticky. Some of these settings, such as the compression options, can be made persistent at channel construction time (see grpc::CreateCustomChannel).

Warning
ClientContext instances should not be reused across rpcs.
The ClientContext instance used for creating an rpc must remain alive and valid for the lifetime of the rpc.

Constructor & Destructor Documentation

◆ ClientContext()

grpc_impl::ClientContext::ClientContext ( )

◆ ~ClientContext()

grpc_impl::ClientContext::~ClientContext ( )

Member Function Documentation

◆ AddMetadata()

void grpc_impl::ClientContext::AddMetadata ( const grpc::string meta_key,
const grpc::string meta_value 
)

Add the (meta_key, meta_value) pair to the metadata associated with a client call.

These are made available at the server side by the grpc::ServerContext::client_metadata() method.

Warning
This method should only be called before invoking the rpc.
Parameters
meta_keyThe metadata key. If meta_value is binary data, it must end in "-bin".
meta_valueThe metadata value. If its value is binary, the key name must end in "-bin".

Metadata must conform to the following format: Custom-Metadata -> Binary-Header / ASCII-Header Binary-Header -> {Header-Name "-bin" } {binary value} ASCII-Header -> Header-Name ASCII-Value Header-Name -> 1*( x30-39 / x61-7A / "_" / "-" / ".") ; 0-9 a-z _ - . ASCII-Value -> 1*( x20-x7E ) ; space and printable ASCII

◆ auth_context()

std::shared_ptr<const grpc::AuthContext> grpc_impl::ClientContext::auth_context ( ) const
inline

Return the authentication context for this client call.

See also
grpc::AuthContext.

◆ c_call()

grpc_call* grpc_impl::ClientContext::c_call ( )
inline

Should be used for framework-level extensions only.

Applications never need to call this method.

◆ census_context()

struct census_context* grpc_impl::ClientContext::census_context ( ) const
inline

◆ compression_algorithm()

grpc_compression_algorithm grpc_impl::ClientContext::compression_algorithm ( ) const
inline

Return the compression algorithm the client call will request be used.

Note that the gRPC runtime may decide to ignore this request, for example, due to resource constraints.

◆ deadline()

std::chrono::system_clock::time_point grpc_impl::ClientContext::deadline ( ) const
inline

Return the deadline for the client call.

◆ debug_error_string()

grpc::string grpc_impl::ClientContext::debug_error_string ( ) const
inline

EXPERIMENTAL debugging API.

if status is not ok() for an RPC, this will return a detailed string of the gRPC Core error that led to the failure. It should not be relied upon for anything other than gaining more debug data in failure cases.

◆ FromServerContext()

static std::unique_ptr<ClientContext> grpc_impl::ClientContext::FromServerContext ( const grpc_impl::ServerContext server_context,
PropagationOptions  options = PropagationOptions() 
)
static

Create a new ClientContext as a child of an incoming server call, according to options (.

See also
PropagationOptions).
Parameters
server_contextThe source server context to use as the basis for constructing the client context.
optionsThe options controlling what to copy from the server_context.
Returns
A newly constructed ClientContext instance based on server_context, with traits propagated (copied) according to options.

◆ GetServerInitialMetadata()

const std::multimap<grpc::string_ref, grpc::string_ref>& grpc_impl::ClientContext::GetServerInitialMetadata ( ) const
inline

Return a collection of initial metadata key-value pairs.

Note that keys may happen more than once (ie, a std::multimap is returned).

Warning
This method should only be called after initial metadata has been received. For streaming calls, see ClientReaderInterface::WaitForInitialMetadata().
Returns
A multimap of initial metadata key-value pairs from the server.

◆ GetServerTrailingMetadata()

const std::multimap<grpc::string_ref, grpc::string_ref>& grpc_impl::ClientContext::GetServerTrailingMetadata ( ) const
inline

Return a collection of trailing metadata key-value pairs.

Note that keys may happen more than once (ie, a std::multimap is returned).

Warning
This method is only callable once the stream has finished.
Returns
A multimap of metadata trailing key-value pairs from the server.

◆ peer()

grpc::string grpc_impl::ClientContext::peer ( ) const

Return the peer uri in a string.

Warning
This value is never authenticated or subject to any security related code. It must not be used for any authentication related functionality. Instead, use auth_context.
Returns
The call's peer URI.

◆ raw_deadline()

gpr_timespec grpc_impl::ClientContext::raw_deadline ( ) const
inline

Return a gpr_timespec representation of the client call's deadline.

◆ set_authority()

void grpc_impl::ClientContext::set_authority ( const grpc::string authority)
inline

Set the per call authority header (see https://tools.ietf.org/html/rfc7540#section-8.1.2.3).

◆ set_cacheable()

void grpc_impl::ClientContext::set_cacheable ( bool  cacheable)
inline

EXPERIMENTAL: Set this request to be cacheable.

If set, grpc is free to use the HTTP GET verb for sending the request, with the possibility of receiving a cached response.

◆ set_census_context()

void grpc_impl::ClientContext::set_census_context ( struct census_context ccp)
inline

Get and set census context.

◆ set_compression_algorithm()

void grpc_impl::ClientContext::set_compression_algorithm ( grpc_compression_algorithm  algorithm)

Set algorithm to be the compression algorithm used for the client call.

Parameters
algorithmThe compression algorithm used for the client call.

◆ set_credentials()

void grpc_impl::ClientContext::set_credentials ( const std::shared_ptr< grpc_impl::CallCredentials > &  creds)

Set credentials for the client call.

A credentials object encapsulates all the state needed by a client to authenticate with a server and make various assertions, e.g., about the client’s identity, role, or whether it is authorized to make a particular call.

It is legal to call this only before initial metadata is sent.

See also
https://grpc.io/docs/guides/auth.html

◆ set_deadline()

template<typename T >
void grpc_impl::ClientContext::set_deadline ( const T &  deadline)
inline

Set the deadline for the client call.

Warning
This method should only be called before invoking the rpc.
Parameters
deadlinethe deadline for the client call. Units are determined by the type used. The deadline is an absolute (not relative) time.

◆ set_fail_fast()

void grpc_impl::ClientContext::set_fail_fast ( bool  fail_fast)
inline

DEPRECATED: Use set_wait_for_ready() instead.

◆ set_idempotent()

void grpc_impl::ClientContext::set_idempotent ( bool  idempotent)
inline

EXPERIMENTAL: Indicate that this request is idempotent.

By default, RPCs are assumed to not be idempotent.

If true, the gRPC library assumes that it's safe to initiate this RPC multiple times.

◆ set_initial_metadata_corked()

void grpc_impl::ClientContext::set_initial_metadata_corked ( bool  corked)
inline

Flag whether the initial metadata should be corked.

If corked is true, then the initial metadata will be coalesced with the write of first message in the stream. As a result, any tag set for the initial metadata operation (starting a client-streaming or bidi-streaming RPC) will not actually be sent to the completion queue or delivered via Next.

Parameters
corkedThe flag indicating whether the initial metadata is to be corked or not.

◆ set_wait_for_ready()

void grpc_impl::ClientContext::set_wait_for_ready ( bool  wait_for_ready)
inline

EXPERIMENTAL: Trigger wait-for-ready or not on this request.

See https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md. If set, if an RPC is made when a channel's connectivity state is TRANSIENT_FAILURE or CONNECTING, the call will not "fail fast", and the channel will wait until the channel is READY before making the call.

◆ SetGlobalCallbacks()

static void grpc_impl::ClientContext::SetGlobalCallbacks ( GlobalCallbacks callbacks)
static

◆ TryCancel()

void grpc_impl::ClientContext::TryCancel ( )

Send a best-effort out-of-band cancel on the call associated with this client context.

The call could be in any stage; e.g., if it is already finished, it may still return success.

There is no guarantee the call will be cancelled.

Note that TryCancel() does not change any of the tags that are pending on the completion queue. All pending tags will still be delivered (though their ok result may reflect the effect of cancellation).

Friends And Related Function Documentation

◆ ::grpc::internal::BlockingUnaryCallImpl

template<class InputMessage , class OutputMessage >
friend class ::grpc::internal::BlockingUnaryCallImpl
friend

◆ ::grpc::internal::CallOpClientRecvStatus

◆ ::grpc::internal::CallOpRecvInitialMetadata

◆ ::grpc::testing::InteropClientContextInspector

friend class ::grpc::testing::InteropClientContextInspector
friend

◆ ::grpc_impl::Channel

friend class ::grpc_impl::Channel
friend

◆ ::grpc_impl::ClientAsyncReader

template<class R >
friend class ::grpc_impl::ClientAsyncReader
friend

◆ ::grpc_impl::ClientAsyncReaderWriter

template<class W , class R >
friend class ::grpc_impl::ClientAsyncReaderWriter
friend

◆ ::grpc_impl::ClientAsyncResponseReader

template<class R >
friend class ::grpc_impl::ClientAsyncResponseReader
friend

◆ ::grpc_impl::ClientAsyncWriter

template<class W >
friend class ::grpc_impl::ClientAsyncWriter
friend

◆ ::grpc_impl::ClientReader

template<class R >
friend class ::grpc_impl::ClientReader
friend

◆ ::grpc_impl::ClientReaderWriter

template<class W , class R >
friend class ::grpc_impl::ClientReaderWriter
friend

◆ ::grpc_impl::ClientWriter

template<class W >
friend class ::grpc_impl::ClientWriter
friend

◆ ::grpc_impl::internal::CallbackUnaryCallImpl

template<class InputMessage , class OutputMessage >
friend class ::grpc_impl::internal::CallbackUnaryCallImpl
friend

◆ ::grpc_impl::internal::ClientCallbackReaderImpl

template<class Response >
friend class ::grpc_impl::internal::ClientCallbackReaderImpl
friend

◆ ::grpc_impl::internal::ClientCallbackReaderWriterImpl

template<class Request , class Response >
friend class ::grpc_impl::internal::ClientCallbackReaderWriterImpl
friend

◆ ::grpc_impl::internal::ClientCallbackUnaryImpl

◆ ::grpc_impl::internal::ClientCallbackWriterImpl

template<class Request >
friend class ::grpc_impl::internal::ClientCallbackWriterImpl
friend

◆ ::grpc_impl::internal::ClientContextAccessor

friend class ::grpc_impl::internal::ClientContextAccessor
friend

The documentation for this class was generated from the following file: