diff --git a/include/grpc++/client_context.h b/include/grpc++/client_context.h index deddc73850c..29d4d96723b 100644 --- a/include/grpc++/client_context.h +++ b/include/grpc++/client_context.h @@ -39,10 +39,10 @@ /// - Initial and trailing metadata coming from the server. /// - Get performance metrics (ie, census). /// -/// Context settings are only relevant to the previous/next call (depending on -/// the method semantics), that is to say, they aren't sticky. Some of these -/// settings, such as the compression options, can be made persistant at channel -/// construction time (see \a grpc::CreateChannel). +/// 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 persistant at channel construction time +/// (see \a grpc::CreateChannel). #ifndef GRPCXX_CLIENT_CONTEXT_H #define GRPCXX_CLIENT_CONTEXT_H @@ -148,8 +148,8 @@ class ClientContext { ClientContext(); ~ClientContext(); - /// Create a new \a ClientContext according to \a options (\see - /// PropagationOptions). + /// Create a new \a ClientContext as a child of an incoming server call, + /// according to \a options (\see PropagationOptions). /// /// \param server_context The source server context to use as the basis for /// constructing the client context. @@ -166,6 +166,8 @@ class ClientContext { /// a client call. These are made available at the server side by the \a /// grpc::ServerContext::client_metadata() method. /// + /// \warning This method should only be called before invoking the rpc. + /// /// \param meta_key The metadata key. If \a meta_value is binary data, it must /// end in "-bin". /// \param meta_value The metadata value. If its value is binary, it must be @@ -177,7 +179,9 @@ class ClientContext { /// Return a collection of initial metadata key-value pairs. Note that keys /// may happen more than once (ie, a \a std::multimap is returned). /// - /// This should only be called upon a successful reply from the server. + /// \warning This method should only be called after initial metadata has been + /// received. For streaming calls, see \a + /// ClientReaderInterface::WaitForInitialMetadata(). /// /// \return A multimap of initial metadata key-value pairs from the server. const std::multimap& GetServerInitialMetadata() { @@ -189,6 +193,8 @@ class ClientContext { /// Return a collection of trailing metadata key-value pairs. Note that keys /// may happen more than once (ie, a \a std::multimap is returned). /// + /// \warning This method is only callable once the stream has finished. + /// /// \return A multimap of metadata trailing key-value pairs from the server. const std::multimap& GetServerTrailingMetadata() { // TODO(yangg) check finished @@ -197,6 +203,8 @@ class ClientContext { /// Set the deadline for the client call. /// + /// \warning This method should only be called before invoking the rpc. + /// /// \param deadline the deadline for the client call. Units are determined by /// the type used. template diff --git a/include/grpc++/completion_queue.h b/include/grpc++/completion_queue.h index b0a041d6fe6..d8c885dd9d1 100644 --- a/include/grpc++/completion_queue.h +++ b/include/grpc++/completion_queue.h @@ -94,7 +94,12 @@ class CompletionQueue : public GrpcLibrary { ~CompletionQueue() GRPC_OVERRIDE; /// Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT. - enum NextStatus { SHUTDOWN, GOT_EVENT, TIMEOUT }; + enum NextStatus { + SHUTDOWN, ///< The completion queue has been shutdown. + GOT_EVENT, ///< Got a new event; \a tag will be filled in with its + ///< associated value; \a ok indicating its success. + TIMEOUT ///< deadline was reached. + }; /// Read from the queue, blocking up to \a deadline (or the queue's shutdown). /// Both \a tag and \a ok are updated upon success (if an event is available @@ -196,7 +201,7 @@ class CompletionQueueTag { }; /// A specific type of completion queue used by the processing of notifications -/// by servers. +/// by servers. Instantiated by \a ServerBuilder. class ServerCompletionQueue : public CompletionQueue { private: friend class ServerBuilder; diff --git a/include/grpc++/credentials.h b/include/grpc++/credentials.h index c8bb6f9b48a..4177e7e071e 100644 --- a/include/grpc++/credentials.h +++ b/include/grpc++/credentials.h @@ -74,18 +74,21 @@ class Credentials : public GrpcLibrary { }; /// Options used to build SslCredentials. -/// -/// pem_roots_cert is the buffer containing the PEM encoding of the server root -/// certificates. If this parameter is empty, the default roots will be used. -/// pem_private_key is the buffer containing the PEM encoding of the client's -/// private key. This parameter can be empty if the client does not have a -/// private key. -/// pem_cert_chain is the buffer containing the PEM encoding of the client's -/// certificate chain. This parameter can be empty if the client does not have -/// a certificate chain. struct SslCredentialsOptions { + /// The buffer containing the PEM encoding of the server root certificates. If + /// this parameter is empty, the default roots will be used. The default + /// roots can be overridden using the \a GRPC_DEFAULT_SSL_ROOTS_FILE_PATH + /// environment variable pointing to a file on the file system containing the + /// roots. grpc::string pem_root_certs; + + /// The buffer containing the PEM encoding of the client's private key. This + /// parameter can be empty if the client does not have a private key. grpc::string pem_private_key; + + /// The buffer containing the PEM encoding of the client's certificate chain. + /// This parameter can be empty if the client does not have a certificate + /// chain. grpc::string pem_cert_chain; }; @@ -95,6 +98,11 @@ struct SslCredentialsOptions { // a channel. A lame channel will be created then and all rpcs will fail on it. /// Builds credentials with reasonable defaults. +/// +/// \warning Only use these credentials when connecting to a Google endpoint. +/// Using these credentials to connect to any other service may result in this +/// service being able to impersonate your client for requests to Google +/// services. std::shared_ptr GoogleDefaultCredentials(); /// Builds SSL Credentials given SSL specific options @@ -102,6 +110,11 @@ std::shared_ptr SslCredentials( const SslCredentialsOptions& options); /// Builds credentials for use when running in GCE +/// +/// \warning Only use these credentials when connecting to a Google endpoint. +/// Using these credentials to connect to any other service may result in this +/// service being able to impersonate your client for requests to Google +/// services. std::shared_ptr ComputeEngineCredentials(); /// Builds service account credentials. @@ -110,6 +123,11 @@ std::shared_ptr ComputeEngineCredentials(); /// token_lifetime_seconds is the lifetime in seconds of each token acquired /// through this service account credentials. It should be positive and should /// not exceed grpc_max_auth_token_lifetime or will be cropped to this value. +/// +/// \warning Only use these credentials when connecting to a Google endpoint. +/// Using these credentials to connect to any other service may result in this +/// service being able to impersonate your client for requests to Google +/// services. std::shared_ptr ServiceAccountCredentials( const grpc::string& json_key, const grpc::string& scope, long token_lifetime_seconds); @@ -125,16 +143,31 @@ std::shared_ptr ServiceAccountJWTAccessCredentials( /// Builds refresh token credentials. /// json_refresh_token is the JSON string containing the refresh token along /// with a client_id and client_secret. +/// +/// \warning Only use these credentials when connecting to a Google endpoint. +/// Using these credentials to connect to any other service may result in this +/// service being able to impersonate your client for requests to Google +/// services. std::shared_ptr RefreshTokenCredentials( const grpc::string& json_refresh_token); /// Builds access token credentials. /// access_token is an oauth2 access token that was fetched using an out of band /// mechanism. +/// +/// \warning Only use these credentials when connecting to a Google endpoint. +/// Using these credentials to connect to any other service may result in this +/// service being able to impersonate your client for requests to Google +/// services. std::shared_ptr AccessTokenCredentials( const grpc::string& access_token); /// Builds IAM credentials. +/// +/// \warning Only use these credentials when connecting to a Google endpoint. +/// Using these credentials to connect to any other service may result in this +/// service being able to impersonate your client for requests to Google +/// services. std::shared_ptr IAMCredentials( const grpc::string& authorization_token, const grpc::string& authority_selector); diff --git a/include/grpc++/server.h b/include/grpc++/server.h index a262368f3ee..c5d991c80fd 100644 --- a/include/grpc++/server.h +++ b/include/grpc++/server.h @@ -44,10 +44,6 @@ #include #include -/// The \a Server class models a gRPC server. -/// -/// Servers are configured and started via \a grpc::ServerBuilder. - struct grpc_server; namespace grpc { @@ -61,6 +57,9 @@ class ServerAsyncStreamingInterface; class ServerCredentials; class ThreadPoolInterface; +/// Models a gRPC server. +/// +/// Servers are configured and started via \a grpc::ServerBuilder. class Server GRPC_FINAL : public GrpcLibrary, private CallHook { public: ~Server(); @@ -126,7 +125,6 @@ class Server GRPC_FINAL : public GrpcLibrary, private CallHook { /// \return bound port number on sucess, 0 on failure. /// /// \warning It's an error to call this method on an already started server. - // TODO(dgq): the "port" part seems to be a misnomer. int AddListeningPort(const grpc::string& addr, ServerCredentials* creds); /// Start the server.