Google Cloud C++ Client  2.1.0
C++ Client Library for Google Cloud Platform
Classes | Typedefs | Enumerations | Functions
google::cloud Namespace Reference

Contains all the Google Cloud C++ Library APIs. More...

Classes

struct  AsyncTimerResult
 The result of an async timer operation. More...
 
class  AsyncOperation
 Represents a pending asynchronous operation. More...
 
class  AsyncStreamingReadWriteRpc
 A streaming read-write RPC. More...
 
class  BackgroundThreads
 A object representing the background threads available to a Client. More...
 
struct  EndpointOption
 Change the endpoint. More...
 
struct  UserAgentProductsOption
 User-agent products to include with each request. More...
 
struct  TracingComponentsOption
 Return whether tracing is enabled for the given component. More...
 
struct  UserProjectOption
 Specifies a project for quota and billing purposes. More...
 
struct  AuthorityOption
 Configure the "authority" attribute. More...
 
class  CompletionQueue
 Call the functor associated with asynchronous operations when they complete. More...
 
class  ConnectionOptions
 The configuration parameters for client connections. More...
 
class  Credentials
 The public interface for Google's Unified Auth Client (GUAC) library. More...
 
struct  DelegatesOption
 Configure the delegates for MakeImpersonateServiceAccountCredentials() More...
 
struct  ScopesOption
 Configure the scopes for MakeImpersonateServiceAccountCredentials() More...
 
struct  AccessTokenLifetimeOption
 Configure the access token lifetime. More...
 
struct  UnifiedCredentialsOption
 A wrapper to store credentials into an options. More...
 
struct  CARootsFilePathOption
 Configures a custom CA (Certificates Authority) certificates file. More...
 
struct  ExperimentalTag
 An argument type to indicate experimental functions. More...
 
class  future
 Implement ISO/IEC TS 19571:2016 future<T>. More...
 
class  promise
 Implement promise<T> as defined in ISO/IEC TS 19571:2016. More...
 
class  future< void >
 Implement ISO/IEC TS 19571:2016 future for void. More...
 
class  promise< void >
 Specialize promise as defined in ISO/IEC TS 19571:2016 for void. More...
 
struct  GrpcCredentialOption
 The gRPC credentials used by clients configured with this object. More...
 
struct  GrpcNumChannelsOption
 The number of transport channels to create. More...
 
struct  GrpcChannelArgumentsOption
 A string-string map of arguments for grpc::ChannelArguments::SetString. More...
 
struct  GrpcChannelArgumentsNativeOption
 The native grpc::ChannelArguments object. More...
 
struct  GrpcTracingOptionsOption
 The TracingOptions to use when printing grpc protocol buffer messages. More...
 
struct  GrpcBackgroundThreadPoolSizeOption
 The size of the background thread pool. More...
 
struct  GrpcCompletionQueueOption
 The CompletionQueue to use for background gRPC work. More...
 
struct  GrpcBackgroundThreadsFactoryOption
 Changes the BackgroundThreadsFactory. More...
 
class  KmsKeyName
 This class identifies a Google Cloud KMS Key. More...
 
struct  LogRecord
 Represents a single log message. More...
 
class  LogBackend
 The logging backend interface. More...
 
class  LogSink
 A sink to receive log records. More...
 
struct  NullStream
 Implements operator<< for all types, without any effect. More...
 
class  Logger
 Define the class to capture a log message. More...
 
class  Logger< false >
 Define the logger for a disabled log level. More...
 
class  Options
 A class that holds option structs indexed by their type. More...
 
class  PollingPolicy
 Control the Cloud C++ client library behavior with respect to polling on long running operations. More...
 
class  GenericPollingPolicy
 Construct a polling policy from existing Retry and Backoff policies. More...
 
class  Project
 This class identifies a Cloud Project. More...
 
class  ErrorInfo
 Describes the cause of the error with structured details. More...
 
class  Status
 Represents success or an error with info about the error. More...
 
class  RuntimeStatusError
 A runtime error that wraps a google::cloud::Status. More...
 
class  StatusOr
 Holds a value or a Status indicating why there is no value. More...
 
class  StreamRange
 A StreamRange<T> is a range of StatusOr<T> where the end-of-stream is indicated by a non-OK Status. More...
 
class  TracingOptions
 The configuration parameters for RPC/protobuf tracing. More...
 

Typedefs

using BackoffPolicy = ::google::cloud::internal::BackoffPolicy
 The base class for backoff policies. More...
 
using ExponentialBackoffPolicy = google::cloud::internal::ExponentialBackoffPolicy
 A truncated exponential backoff policy with randomized periods. More...
 
using CommonOptionList = OptionList< EndpointOption, UserAgentProductsOption, TracingComponentsOption, UserProjectOption, AuthorityOption >
 A list of all the common options. More...
 
using BackgroundThreadsFactory = std::function< std::unique_ptr< BackgroundThreads >()>
 
using GrpcOptionList = OptionList< GrpcCredentialOption, GrpcNumChannelsOption, GrpcChannelArgumentsOption, GrpcChannelArgumentsNativeOption, GrpcTracingOptionsOption, GrpcBackgroundThreadPoolSizeOption, GrpcCompletionQueueOption, GrpcBackgroundThreadsFactoryOption >
 A list of all the gRPC options. More...
 
using IamUpdater = std::function< absl::optional< google::iam::v1::Policy >(google::iam::v1::Policy)>
 Used in the SetIamPolicy() read-modify-write cycles where an etag helps prevent simultaneous updates of a policy from overwriting each other. More...
 
template<typename T >
using optional = absl::optional< T >
 Alias template for google::cloud::optional. More...
 
template<typename... T>
using OptionList = internal::TypeList< T... >
 A template to hold a list of "option" types. More...
 

Enumerations

enum class  Idempotency { kIdempotent , kNonIdempotent }
 Whether a request is idempotent. More...
 
enum class  Severity : int {
  GCP_LS_TRACE , GCP_LS_DEBUG , GCP_LS_INFO , GCP_LS_NOTICE ,
  GCP_LS_WARNING , GCP_LS_ERROR , GCP_LS_CRITICAL , GCP_LS_ALERT ,
  GCP_LS_FATAL , GCP_LS_HIGHEST = GCP_LS_FATAL , GCP_LS_LOWEST = GCP_LS_TRACE , GCP_LS_LOWEST_ENABLED = GOOGLE_CLOUD_CPP_LOGGING_MIN_SEVERITY_ENABLED
}
 Define the severity levels for Google Cloud Platform C++ Libraries logging. More...
 
enum class  StatusCode {
  kOk = 0 , kCancelled = 1 , kUnknown = 2 , kInvalidArgument = 3 ,
  kDeadlineExceeded = 4 , kNotFound = 5 , kAlreadyExists = 6 , kPermissionDenied = 7 ,
  kUnauthenticated = 16 , kResourceExhausted = 8 , kFailedPrecondition = 9 , kAborted = 10 ,
  kOutOfRange = 11 , kUnimplemented = 12 , kInternal = 13 , kUnavailable = 14 ,
  kDataLoss = 15
}
 Well-known status codes with grpc::StatusCode-compatible values. More...
 

Functions

std::shared_ptr< CredentialsMakeInsecureCredentials ()
 Create insecure (aka anonymous, aka unauthenticated) credentials. More...
 
std::shared_ptr< CredentialsMakeGoogleDefaultCredentials ()
 Creates the default credentials. More...
 
std::shared_ptr< CredentialsMakeAccessTokenCredentials (std::string const &access_token, std::chrono::system_clock::time_point expiration)
 Creates credentials with a fixed access token. More...
 
std::shared_ptr< CredentialsMakeImpersonateServiceAccountCredentials (std::shared_ptr< Credentials > base_credentials, std::string target_service_account, Options opts={})
 Creates credentials for service account impersonation. More...
 
std::shared_ptr< CredentialsMakeServiceAccountCredentials (std::string json_object)
 Creates service account credentials from a service account key. More...
 
template<typename T >
future< typename internal::make_ready_return< T >::type > make_ready_future (T &&t)
 Create a future<void> that is immediately ready. More...
 
future< void > make_ready_future ()
 Create a future<void> that is immediately ready. More...
 
google::cloud::Status MakeStatusFromRpcError (grpc::Status const &status)
 Creates a google::cloud::Status from a grpc::Status. More...
 
google::cloud::Status MakeStatusFromRpcError (grpc::StatusCode code, std::string what)
 Creates a google::cloud::Status from a grpc::StatusCode and description. More...
 
google::cloud::Status MakeStatusFromRpcError (google::rpc::Status const &proto)
 Creates a google::cloud::Status from a google:rpc::Status proto. More...
 
StatusOr< KmsKeyNameMakeKmsKeyName (std::string const &full_name)
 Constructs a KmsKeyName from the given full_name. More...
 
std::ostream & operator<< (std::ostream &os, Severity x)
 Streaming operator, writes a human readable representation. More...
 
std::ostream & operator<< (std::ostream &os, LogRecord const &rhs)
 Default formatting of a LogRecord. More...
 
StatusOr< ProjectMakeProject (std::string const &full_name)
 Constructs a Project from the given full_name. More...
 
std::string StatusCodeToString (StatusCode code)
 
std::ostream & operator<< (std::ostream &os, StatusCode code)
 
template<typename T >
bool operator== (StatusOr< T > const &a, StatusOr< T > const &b)
 
template<typename T >
bool operator!= (StatusOr< T > const &a, StatusOr< T > const &b)
 
template<typename T >
StatusOr< T > make_status_or (T rhs)
 
constexpr int version_major ()
 The Google Cloud Storage C++ Client major version. More...
 
constexpr int version_minor ()
 The Google Cloud Storage C++ Client minor version. More...
 
constexpr int version_patch ()
 The Google Cloud Storage C++ Client patch version. More...
 
constexpr int version ()
 A single integer representing the Major/Minor/Patch version. More...
 
std::string version_string ()
 The version as a string, in MAJOR.MINOR.PATCH+gitrev format. More...
 

Control behaviour on unrecoverable errors.

The following APIs are google::cloud counterpart for std::{set,get}_terminate functions.

If exceptions are not enabled via GOOGLE_CLOUD_CPP_HAVE_EXCEPTIONS, calling any function from throw_delegate.h will result in calling the handler installed via this API. By default, a call to std::abort() is used.

using TerminateHandler = std::function< void(char const *msg)>
 Terminate handler. More...
 
TerminateHandler SetTerminateHandler (TerminateHandler f)
 Install terminate handler and get the old one atomically. More...
 
TerminateHandler GetTerminateHandler ()
 Get the currently installed handler. More...
 
void Terminate (char const *msg)
 Invoke the currently installed handler. More...
 

Detailed Description

Contains all the Google Cloud C++ Library APIs.

Typedef Documentation

◆ BackgroundThreadsFactory

using google::cloud::BackgroundThreadsFactory = typedef std::function<std::unique_ptr<BackgroundThreads>()>

Definition at line 127 of file grpc_options.h.

◆ BackoffPolicy

using google::cloud::BackoffPolicy = typedef ::google::cloud::internal::BackoffPolicy

The base class for backoff policies.

Definition at line 26 of file backoff_policy.h.

◆ CommonOptionList

A list of all the common options.

Definition at line 104 of file common_options.h.

◆ ExponentialBackoffPolicy

using google::cloud::ExponentialBackoffPolicy = typedef google::cloud::internal::ExponentialBackoffPolicy

A truncated exponential backoff policy with randomized periods.

Definition at line 29 of file backoff_policy.h.

◆ GrpcOptionList

A list of all the gRPC options.

Definition at line 153 of file grpc_options.h.

◆ IamUpdater

using google::cloud::IamUpdater = typedef std::function<absl::optional<google::iam::v1::Policy>( google::iam::v1::Policy)>

Used in the SetIamPolicy() read-modify-write cycles where an etag helps prevent simultaneous updates of a policy from overwriting each other.

The updater is called with a recently fetched policy, and should either return an empty optional if no changes are required, or return a new policy to be set. In the latter case the updater should either (1) set the etag of the returned policy to that of the recently fetched policy (strongly suggested), or (2) not set the etag at all.

In case (1) if the etag does not match the existing policy (i.e., there has been an intermediate update), this update is dropped and a new cycle is initiated. In case (2) the existing policy is overwritten blindly.

Definition at line 41 of file iam_updater.h.

◆ optional

template<typename T >
using google::cloud::optional = typedef absl::optional<T>

Alias template for google::cloud::optional.

Deprecated:
this alias is deprecated; use absl::optional<T> directly.

Definition at line 31 of file optional.h.

◆ OptionList

template<typename... T>
using google::cloud::OptionList = typedef internal::TypeList<T...>

A template to hold a list of "option" types.

This can be a useful way to create meaningful lists of options. For example, there could be a list containing all the gRPC options. Or a list of all ProductX options. This gives us a way to link to lists of options with doxygen, and to do some checking about what options a function may expect.

Definition at line 254 of file options.h.

◆ TerminateHandler

using google::cloud::TerminateHandler = typedef std::function<void(char const* msg)>

Terminate handler.

It should handle the error, whose description are given in msg and should never return.

Definition at line 41 of file terminate_handler.h.

Enumeration Type Documentation

◆ Idempotency

Whether a request is idempotent.

When a RPC fails with a retryable error, the google-cloud-cpp client libraries automatically retry the RPC if the RPC is idempotent. For each service, the library define a policy that determines whether a given request is idempotent. In many cases this can be determined statically, for example, read-only operations are always idempotent. In some cases, the contents of the request may need to be examined to determine if the operation is idempotent. For example, performing operations with pre-conditions, such that the pre-conditions change when the operation succeed, is typically idempotent.

Applications may override the default idempotency policy, though we anticipate that this would be needed only in very rare circumstances. A few examples include:

  • In some services deleting "the most recent" entry may be idempotent if the system has been configured to keep no history or versions, as the deletion may succeed only once. In contrast, deleting "the most recent entry" is not idempotent if the system keeps multiple versions. Google Cloud Storage or Bigtable can be configured either way.
  • In some applications, creating a duplicate entry may be acceptable as the system will deduplicate them later. In such systems it may be preferable to retry the operation even though it is not idempotent.
Enumerator
kIdempotent 

The operation is idempotent and can be retried after a transient failure.

kNonIdempotent 

The operation is not idempotent and should not be retried after a transient failure.

Definition at line 55 of file idempotency.h.

◆ Severity

enum google::cloud::Severity : int
strong

Define the severity levels for Google Cloud Platform C++ Libraries logging.

These are modelled after the severity level in syslog(1) and many derived tools.

We force the enum to be represented as an int because we will store the values in an std::atomic<> and the implementations usually optimize std::atomic<int> but not std::atomic<Foo>

Enumerator
GCP_LS_TRACE 

Use this level for messages that indicate the code is entering and leaving functions.

GCP_LS_DEBUG 

Use this level for debug messages that should not be present in production.

GCP_LS_INFO 

Informational messages, such as normal progress.

GCP_LS_NOTICE 

Informational messages, such as unusual, but expected conditions.

GCP_LS_WARNING 

An indication of problems, users may need to take action.

GCP_LS_ERROR 

An error has been detected.

Do not use for normal conditions, such as remote servers disconnecting.

GCP_LS_CRITICAL 

The system is in a critical state, such as running out of local resources.

GCP_LS_ALERT 

The system is at risk of immediate failure.

GCP_LS_FATAL 

The system is unusable. GCP_LOG(FATAL) will call std::abort().

GCP_LS_HIGHEST 

The highest possible severity level.

GCP_LS_LOWEST 

The lowest possible severity level.

GCP_LS_LOWEST_ENABLED 

The lowest level that is enabled at compile-time.

Definition at line 183 of file log.h.

◆ StatusCode

Well-known status codes with grpc::StatusCode-compatible values.

The semantics of these values are documented in: https://grpc.io/grpc/cpp/classgrpc_1_1_status.html

Enumerator
kOk 

Not an error; returned on success.

kCancelled 
kUnknown 
kInvalidArgument 
kDeadlineExceeded 
kNotFound 
kAlreadyExists 
kPermissionDenied 
kUnauthenticated 
kResourceExhausted 
kFailedPrecondition 
kAborted 
kOutOfRange 
kUnimplemented 
kInternal 
kUnavailable 
kDataLoss 

Definition at line 35 of file status.h.

Function Documentation

◆ GetTerminateHandler()

TerminateHandler google::cloud::GetTerminateHandler ( )

Get the currently installed handler.

Returns
The currently installed handler.

◆ make_ready_future() [1/2]

future<void> google::cloud::make_ready_future ( )
inline

Create a future<void> that is immediately ready.

Definition at line 207 of file future_void.h.

◆ make_ready_future() [2/2]

template<typename T >
future<typename internal::make_ready_return<T>::type> google::cloud::make_ready_future ( T &&  t)
inline

Create a future<void> that is immediately ready.

Definition at line 217 of file future_generic.h.

◆ make_status_or()

template<typename T >
StatusOr<T> google::cloud::make_status_or ( rhs)

Definition at line 294 of file status_or.h.

◆ MakeAccessTokenCredentials()

std::shared_ptr<Credentials> google::cloud::MakeAccessTokenCredentials ( std::string const &  access_token,
std::chrono::system_clock::time_point  expiration 
)

Creates credentials with a fixed access token.

These credentials are useful when using an out-of-band mechanism to fetch access tokens. Note that access tokens are time limited, you will need to manually refresh the tokens created by the

See also
https://cloud.google.com/docs/authentication for more information on authentication in GCP.

◆ MakeGoogleDefaultCredentials()

std::shared_ptr<Credentials> google::cloud::MakeGoogleDefaultCredentials ( )

Creates the default credentials.

These are the most commonly used credentials, and are expected to meet the needs of most applications. The Google Default Credentials conform to aip/4110. Consider using these credentials when:

  • Your application is deployed to a GCP environment such as GCE, GKE, or Cloud Run. Each of these deployment environments provides a default service account to the application, and offers mechanisms to change the default credentials without any code changes to your application.
  • You are testing or developing the application on a workstation (physical or virtual). These credentials will use your preferences as set with gcloud auth application-default. These preferences can be your own GCP user credentials, or some service account.
  • Regardless of where your application is running, you can use the GOOGLE_APPLICATION_CREDENTIALS environment variable to override the defaults. This environment variable should point to a file containing a service account key file, or a JSON object describing your user credentials.
See also
https://cloud.google.com/docs/authentication for more information on authentication in GCP.

◆ MakeImpersonateServiceAccountCredentials()

std::shared_ptr<Credentials> google::cloud::MakeImpersonateServiceAccountCredentials ( std::shared_ptr< Credentials base_credentials,
std::string  target_service_account,
Options  opts = {} 
)

Creates credentials for service account impersonation.

Service account impersonation allows one account (user or service account) to act as a second account. This can be useful in multi-tenant services, where the service may perform some actions with an specific account associated with a tenant. The tenant can grant or restrict permissions to this tenant account.

When using service account impersonation is important to distinguish between the credentials used to obtain the target account credentials (the base_credentials) parameter, and the credentials representing the target_service_account.

Use AccessTokenLifetimeOption to configure the maximum lifetime of the obtained credentials. The default is 1h (3600s), see IAM quotas for the limits set by the platform and how to override them.

Use DelegatesOption to configure a sequence of intermediate service account, each of which has permissions to impersonate the next and the last one has permissions to impersonate target_service_account.

Use ScopesOption to restrict the authentication scope for the obtained credentials. See below for possible values.

See also
https://cloud.google.com/docs/authentication for more information on authentication in GCP.
https://cloud.google.com/iam/docs/impersonating-service-accounts for information on managing service account impersonation.
https://developers.google.com/identity/protocols/oauth2/scopes for authentication scopes in Google Cloud Platform.

◆ MakeInsecureCredentials()

std::shared_ptr<Credentials> google::cloud::MakeInsecureCredentials ( )

Create insecure (aka anonymous, aka unauthenticated) credentials.

These credentials are mostly intended for testing. Integration tests running against an emulator do not need to authenticate. In fact, it may be impossible to connect to an emulator using SSL/TLS because the emulators typically run without secure communication.

In addition, unit tests may benefit from using these credentials: loading the default credentials unnecessarily slows down the unit tests, and in some CI environments the credentials may fail to load, creating confusing warnings and sometimes even errors.

◆ MakeKmsKeyName()

StatusOr<KmsKeyName> google::cloud::MakeKmsKeyName ( std::string const &  full_name)

Constructs a KmsKeyName from the given full_name.

Returns a non-OK Status if full_name is improperly formed.

◆ MakeProject()

StatusOr<Project> google::cloud::MakeProject ( std::string const &  full_name)

Constructs a Project from the given full_name.

Returns a non-OK Status if full_name is improperly formed.

◆ MakeServiceAccountCredentials()

std::shared_ptr<Credentials> google::cloud::MakeServiceAccountCredentials ( std::string  json_object)

Creates service account credentials from a service account key.

A service account is an account for an application or compute workload instead of an individual end user. The recommended practice is to use Google Default Credentials, which relies on the configuration of the Google Cloud system hosting your application (GCE, GKE, Cloud Run) to authenticate your workload or application. But sometimes you may need to create and download a service account key, for example, to use a service account when running your application on a system that is not part of Google Cloud.

Service account credentials are used in this latter case.

You can create multiple service account keys for a single service account. When you create a service account key, the key is returned as string, in the format described by aip/4112. This string contains an id for the service account, as well as the cryptographical materials (a RSA private key) required to authenticate the caller.

Therefore, services account keys should be treated as any other secret with security implications. Think of them as unencrypted passwords. Do not store them where unauthorized persons or programs may read them.

As stated above, most applications should probably use default credentials, maybe pointing them to a file with these contents. Using this function may be useful when the service account key is obtained from Cloud Secret Manager or a similar service.

◆ MakeStatusFromRpcError() [1/3]

google::cloud::Status google::cloud::MakeStatusFromRpcError ( google::rpc::Status const &  proto)

Creates a google::cloud::Status from a google:rpc::Status proto.

Some gRPC services return the google::rpc::Status proto for errors. The libraries in google-cloud-cpp represent these errors using a google::cloud::Status.

◆ MakeStatusFromRpcError() [2/3]

google::cloud::Status google::cloud::MakeStatusFromRpcError ( grpc::Status const &  status)

Creates a google::cloud::Status from a grpc::Status.

◆ MakeStatusFromRpcError() [3/3]

google::cloud::Status google::cloud::MakeStatusFromRpcError ( grpc::StatusCode  code,
std::string  what 
)

Creates a google::cloud::Status from a grpc::StatusCode and description.

◆ operator!=()

template<typename T >
bool google::cloud::operator!= ( StatusOr< T > const &  a,
StatusOr< T > const &  b 
)

Definition at line 289 of file status_or.h.

◆ operator<<() [1/3]

std::ostream& google::cloud::operator<< ( std::ostream &  os,
LogRecord const &  rhs 
)

Default formatting of a LogRecord.

◆ operator<<() [2/3]

std::ostream& google::cloud::operator<< ( std::ostream &  os,
Severity  x 
)

Streaming operator, writes a human readable representation.

◆ operator<<() [3/3]

std::ostream& google::cloud::operator<< ( std::ostream &  os,
StatusCode  code 
)

◆ operator==()

template<typename T >
bool google::cloud::operator== ( StatusOr< T > const &  a,
StatusOr< T > const &  b 
)

Definition at line 281 of file status_or.h.

◆ SetTerminateHandler()

TerminateHandler google::cloud::SetTerminateHandler ( TerminateHandler  f)

Install terminate handler and get the old one atomically.

Parameters
fthe handler. It should never return, behaviour is undefined otherwise.
Returns
Previously set handler.

◆ StatusCodeToString()

std::string google::cloud::StatusCodeToString ( StatusCode  code)

◆ Terminate()

void google::cloud::Terminate ( char const *  msg)

Invoke the currently installed handler.

Parameters
msgDetails about the error.

This function should never return.

◆ version()

constexpr int google::cloud::version ( )
constexpr

A single integer representing the Major/Minor/Patch version.

Definition at line 86 of file version.h.

◆ version_major()

constexpr int google::cloud::version_major ( )
constexpr

The Google Cloud Storage C++ Client major version.

See also
https://semver.org/spec/v2.0.0.html for details.

Definition at line 64 of file version.h.

◆ version_minor()

constexpr int google::cloud::version_minor ( )
constexpr

The Google Cloud Storage C++ Client minor version.

See also
https://semver.org/spec/v2.0.0.html for details.

Definition at line 71 of file version.h.

◆ version_patch()

constexpr int google::cloud::version_patch ( )
constexpr

The Google Cloud Storage C++ Client patch version.

See also
https://semver.org/spec/v2.0.0.html for details.

Definition at line 78 of file version.h.

◆ version_string()

std::string google::cloud::version_string ( )

The version as a string, in MAJOR.MINOR.PATCH+gitrev format.