Denotes the current state of an HttpRequest's lifecycel. More...

#include "client/transport/http_types.h"

Public Types
enum	StateCode { UNSENT, QUEUED, PENDING, COMPLETED, COULD_NOT_SEND, TIMED_OUT, CANCELLED, ABORTED, _NUM_STATES_ }
	Denotes a state in the HttpRequest lifecycle. More...
Public Member Functions
	HttpRequestState ()
	Standard constructor.
virtual	~HttpRequestState ()
	Destroys this instance.
void	DestroyWhenDone ()
	Destroys this instance when it is finished waiting.
StateCode	state_code () const LOCKS_EXCLUDED(mutex_)
	Gets lifecycle state code.
void	TransitionAndNotifyIfDone (StateCode code) LOCKS_EXCLUDED(mutex_)
	Transition to a new lifecycle state.
util::Status	AutoTransitionAndNotifyIfDone () LOCKS_EXCLUDED(mutex_)
	Transitions the state as applicable based on the transport_status() or http_code().
void	set_transport_status (const util::Status &status) LOCKS_EXCLUDED(mutex_)
	Sets the transport-level status for the request.
util::Status	transport_status () const LOCKS_EXCLUDED(mutex_)
	Returns the transport-level status.
util::Status	status () const LOCKS_EXCLUDED(mutex_)
	Returns the overall status for this request.
int	http_code () const
	Returns the HTTP status code returned in the response.
void	set_http_code (int http_code)
	Sets the HTTP status code returned by the HTTP server.
bool	done () const LOCKS_EXCLUDED(mutex_)
	Returns whether or not the request has completely finished executing.
bool	ok () const LOCKS_EXCLUDED(mutex_)
	Returns whether or not an error has been encountered.
bool	WaitUntilDone (int64 timeout_ms=kint64max) LOCKS_EXCLUDED(mutex_)
	Blocks the callers thread until the state is done (the request completes) or the timeout has elapsed.
HttpResponse *	response () const LOCKS_EXCLUDED(mutex_)
	Gets the respose objecta associated with the request.
Friends
class	HttpRequest

Detailed Description

Denotes the current state of an HttpRequest's lifecycel.

The state includes the StateCode in its state machine progress as well as status and response data. Normally the state is created as an attribute to an HttpRequest or HttpResponse -- you do not typically instantiate these directly yourself.

The state is shared between an HttpRequest and its HttpResponse such that it is accessible by either. It will remain valid until both the request and response have been destroyed.

This class is thread-safe.

Member Enumeration Documentation

enum StateCode

Denotes a state in the HttpRequest lifecycle.

State Code	Done	Ok	Description	Possible Transitions
UNSENT	-	Y	The request has not yet been sent.	QUEUED, PENDING, COULD_NOT_SEND, CANCELLED
QUEUED	-	Y	The request has been queued to send (async) but has not yet been sent.	PENDING, COULD_NOT_SEND, CANCELLED,
PENDING	-	Y	The request has been sent (either in part or whole) but a response has not yet been received.	COMPLETED, COULD_NOT_SEND, TIMED_OUT, ABORTED
COMPLETED	Y	Y	A response was received from the server. The response might have been an HTTP error, but was a valid HTTP response.	-
COULD_NOT_SEND	Y	-	An error prevented the request from being sent or response from being received.	-
TIMED_OUT	Y	-	Request was sent but timed out before response arrived.	-
CANCELLED	Y	-	Indicates that the request was cancelled before it was sent.	-
ABORTED	Y	-	Used to signal callback it will never be called.	-
_NUM_STATES_	-	-	An internal marker used to count the nuber of states.	-

Enumerator:

UNSENT
QUEUED
PENDING
COMPLETED
COULD_NOT_SEND
TIMED_OUT
CANCELLED
ABORTED
_NUM_STATES_

Constructor & Destructor Documentation

HttpRequestState ( )

Standard constructor.

virtual ~HttpRequestState ( ) [virtual]

Destroys this instance.

Member Function Documentation

util::Status AutoTransitionAndNotifyIfDone ( )

Transitions the state as applicable based on the transport_status() or http_code().

This function deteremins what the state_code should be based on the transport_status() and http_code() values.

An http_code indicating that the HTTP request is no longer outstanding will transition into StateCode::COMPLETED (even if the http code is an error). Only (specialized) HttpRequest classes should set the http_code attribute.

Returns:: The overall request status after the transition. A failure status indicates that the HttpRequest failed, not a failure to transition.

void DestroyWhenDone ( )

Destroys this instance when it is finished waiting.

Will destory immediately if it isnt waiting.

bool done ( ) const

Returns whether or not the request has completely finished executing.

Returns:: true if the state denotes done, false otherwise

See also:: StateCode

int http_code ( ) const [inline]

Returns the HTTP status code returned in the response.

Precondition:: request_state() == COMPLETED

Returns:: 0 if the request_state has not completed, including transport errors.

bool ok ( ) const

Returns whether or not an error has been encountered.

Returns:: true if the state code denotes ok, false otherwise

See also:: StateCode

HttpResponse* response ( ) const

Gets the respose objecta associated with the request.

void set_http_code ( int http_code ) [inline]

Sets the HTTP status code returned by the HTTP server.

void set_transport_status ( const util::Status & status )

Sets the transport-level status for the request.

The transport-level status can be used to determine whether the communication between this client and the service was ok or not independent of whether the service was able to actually perform the request. HTTP errors are application-level failures, but transport-level success because the complete HTTP messaging was able to take place.

Parameters:

[in] status The transport-level status.

StateCode state_code ( ) const

Gets lifecycle state code.

Note:: Only HttpTransports should set the state attribute.

util::Status status ( ) const

Returns the overall status for this request.

If the transport_status is a failure, then this status will reflect that. If the transport_status is ok then this status will be determined by the http_code. Often for HTTP level errors, HttpResponse::body_reader() contains additional error information that wont be contained in the status.

void TransitionAndNotifyIfDone ( StateCode code )

Transition to a new lifecycle state.

Parameters:

[in] code Specifies the new state_code().

If this transitions into a done() state for the first time then it will call the callback, if one has been bound, then signal any threads waiting on this state. This method does not cause the instance to be destroyed if it was configured to self-destruct; that is up to the caller.

util::Status transport_status ( ) const

Returns the transport-level status.

Returns:: failure status only if a transport error was encountered. The status will be ok in an UNSENT state.

bool WaitUntilDone ( int64 timeout_ms = kint64max )

Blocks the callers thread until the state is done (the request completes) or the timeout has elapsed.

Parameters:

[in] timeout_ms (optional, forever if not specified)

Returns:: true if the request is done, false if the timeout expired. If the request times out then true is returned (because the request is done).

If the request had the destroy_when_done option set then it will no longer be available, nor will this state instance. Even if false is returned, indicating that the request is not done, you should not assume that the request or state instance is still valid because it could have just completed since this method returned.

Friends And Related Function Documentation

friend class HttpRequest [friend]

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

googleapis/client/transport/http_types.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation