Poco::RemotingNG::REST

class Transport

File Information

Library: RemotingNG/REST
Package: REST
Header: Poco/RemotingNG/REST/Transport.h

Description

The Transport implementation for RemotingNG REST.

This transport implements REST-style APIs based on the OpenAPI specification (formerly the Swagger RESTful API) (see <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md> for the specification).

The transport supports HTTP Basic and HTTP Digest authentication. HTTP Digest authentication is not supported for one-way requests.

Inheritance

Direct Base Classes: Poco::RemotingNG::Transport

All Base Classes: Poco::RefCountedObject, Poco::RemotingNG::AttributedObject, Poco::RemotingNG::Transport

Member Summary

Member Functions: beginMessage, beginRequest, connect, connected, disconnect, enableCompression, enableKeepAlive, endPoint, endRequest, getAuthentication, getCookieStore, getCredentials, getCustomHeader, getKeepAliveTimeout, getPassword, getProxyConfig, getTimeout, getUserAgent, getUsername, hasCustomHeader, httpSessionFactory, isCompressionEnabled, isKeepAliveEnabled, prepareRequest, removeCustomHeader, requireSession, sendMessage, sendRequest, setAuthentication, setCookieStore, setCredentials, setCustomHeader, setKeepAliveTimeout, setPassword, setProxyConfig, setTimeout, setUserAgent, setUsername

Inherited Functions: beginMessage, beginRequest, clearAttributes, connect, connected, countAttributes, disconnect, duplicate, endPoint, endRequest, enumerateAttributes, getAttribute, hasAttribute, lock, operator =, referenceCount, release, removeAttribute, sendMessage, sendRequest, setAttribute, unlock

Enumerations

AuthMode

Authentication mode.

AUTH_NONE = 0

No authentication.

AUTH_BASIC = 1

HTTP Basic Authentication only (credentials are always sent).

AUTH_DIGEST = 2

HTTP Digest Authentication only.

AUTH_ANY = 3

HTTP Basic or Digest authentication (whichever the server requests).

AUTH_BEARER = 4

OAuth 2.0 Bearer Token (Credentials::ATTR_TOKEN, Credentials::ATTR_MECHANISM).

AUTH_CUSTOM = 5

Use custom authentication header (Credentials::ATTR_TOKEN, Credentials::ATTR_MECHANISM).

Constructors

Transport

Transport();

Creates a Transport for REST.

Destructor

~Transport virtual

~Transport();

Destroys the Transport.

Member Functions

beginMessage

Poco::RemotingNG::Serializer & beginMessage(
    const Poco::RemotingNG::Identifiable::ObjectId & oid,
    const Poco::RemotingNG::Identifiable::TypeId & tid,
    const std::string & messageName,
    Poco::RemotingNG::SerializerBase::MessageType messageType
);

beginRequest

Poco::RemotingNG::Serializer & beginRequest(
    const Poco::RemotingNG::Identifiable::ObjectId & oid,
    const Poco::RemotingNG::Identifiable::TypeId & tid,
    const std::string & messageName,
    Poco::RemotingNG::SerializerBase::MessageType messageType
);

connect virtual

void connect(
    const std::string & endPoint
);

See also: Poco::RemotingNG::Transport::connect()

connected virtual

bool connected() const;

See also: Poco::RemotingNG::Transport::connected()

disconnect virtual

void disconnect();

See also: Poco::RemotingNG::Transport::disconnect()

enableCompression

void enableCompression(
    bool enable
);

Enables or disables HTTP compression via GZIP Content-Encoding for requests. This is normally disabled, due to a lack of support by most servers.

Regardless of this setting, server responses can always be compressed using GZIP Content-Encoding.

enableKeepAlive

void enableKeepAlive(
    bool enable
);

Enables or disables HTTP/1.1 persistent connections.

The Transport must be connected, otherwise a Poco::IllegalStateException will be thrown.

endPoint virtual

const std::string & endPoint() const;

See also: Poco::RemotingNG::Transport::endPoint()

endRequest virtual

void endRequest();

See also: Poco::RemotingNG::Transport::endRequest()

getAuthentication

AuthMode getAuthentication() const;

Returns the authentication mode.

getCookieStore

CookieStore::Ptr getCookieStore() const;

Returns the CookieStore.

getCredentials inline

const Poco::RemotingNG::Credentials & getCredentials() const;

Returns a const reference to the internal Credentials object.

getCustomHeader

const std::string & getCustomHeader(
    const std::string & name
) const;

Returns the value of the custom HTTP header with the given name.

Throws a Poco::NotFoundException if the custom header with the given name does not exist.

getKeepAliveTimeout

Poco::Timespan getKeepAliveTimeout() const;

Returns the timeout for HTTP/1.1 persistent connections.

The Transport must be connected, otherwise a Poco::IllegalStateException will be thrown.

getPassword

const std::string & getPassword() const;

Deprecated. This function issc_deprecated.

Returns the password for HTTP authentication.

Deprecated. Code should be changed to use getCredentials().

getProxyConfig

const Poco::Net::HTTPClientSession::ProxyConfig & getProxyConfig() const;

Returns the proxy configuration.

getTimeout

Poco::Timespan getTimeout() const;

Returns the HTTP timeout.

The Transport must be connected, otherwise a Poco::IllegalStateException will be thrown.

getUserAgent

const std::string & getUserAgent() const;

Returns the value of the User-Agent header sent with REST HTTP requests, or an empty string if no User-Agent value has been set.

getUsername

const std::string & getUsername() const;

Deprecated. This function issc_deprecated.

Returns the username for HTTP authentication.

Deprecated. Code should be changed to use getCredentials().

hasCustomHeader

bool hasCustomHeader(
    const std::string & name
) const;

Returns true if a custom HTTP header with the given name has been set.

httpSessionFactory static inline

static Poco::Net::HTTPSessionFactory & httpSessionFactory();

Returns the Poco::Net::HTTPSessionFactory instance used by the transport.

isCompressionEnabled

bool isCompressionEnabled() const;

Returns true iff HTTP compression (GZIP) is enabled for requests. Default is disabled.

isKeepAliveEnabled

bool isKeepAliveEnabled() const;

Returns true iff HTTP/1.1 persistent connections are enabled.

The Transport must be connected, otherwise a Poco::IllegalStateException will be thrown.

removeCustomHeader

void removeCustomHeader(
    const std::string & name
);

Removes a custom HTTP header previously added with setCustomHeader().

sendMessage

void sendMessage(
    const Poco::RemotingNG::Identifiable::ObjectId & oid,
    const Poco::RemotingNG::Identifiable::TypeId & tid,
    const std::string & messageName,
    Poco::RemotingNG::SerializerBase::MessageType messageType
);

sendRequest

Poco::RemotingNG::Deserializer & sendRequest(
    const Poco::RemotingNG::Identifiable::ObjectId & oid,
    const Poco::RemotingNG::Identifiable::TypeId & tid,
    const std::string & messageName,
    Poco::RemotingNG::SerializerBase::MessageType messageType
);

setAuthentication

void setAuthentication(
    AuthMode authMode
);

Sets the authentication mode.

setCookieStore

void setCookieStore(
    CookieStore::Ptr pCookieStore
);

Sets the CookieStore.

setCredentials

void setCredentials(
    const Poco::RemotingNG::Credentials & creds
);

Sets the credentials which must match the specified authentication mode (see setAuthentication()).

For AUTH_BASIC, AUTH_DIGEST and AUTH_ANY, the Credentials object must contain a Credentials::ATTR_USERNAME and a Credentials::ATTR_PASSWORD attribute.

For AUTH_BEARER, the Credentials object must contain a Credentials::ATTR_TOKEN attribute containing the bearer token. Optionally, a Credentials::ATTR_MECHANISM attribute can be specified to override the default authentication scheme ("Bearer").

For AUTH_CUSTOM, the Credentials object must contain a Credentials::ATTR_TOKEN attribute containing the value passed in the custom authentication header, as well as a Credentials::ATTR_MECHANISM attribute specifying the name of the request header.

setCustomHeader

void setCustomHeader(
    const std::string & name,
    const std::string & value
);

Adds a custom HTTP header to the HTTP request.

setKeepAliveTimeout

void setKeepAliveTimeout(
    const Poco::Timespan & timeout
);

Sets the timeout for HTTP/1.1 persistent connections.

The Transport must be connected, otherwise a Poco::IllegalStateException will be thrown.

setPassword

void setPassword(
    const std::string & password
);

Deprecated. This function issc_deprecated.

Sets the password for HTTP authentication.

Deprecated. Code should be changed to use setCredentials().

setProxyConfig

void setProxyConfig(
    const Poco::Net::HTTPClientSession::ProxyConfig & proxyConfig
);

Sets the proxy configuration.

setTimeout

void setTimeout(
    const Poco::Timespan & timeout
);

Sets the HTTP timeout.

The Transport must be connected, otherwise a Poco::IllegalStateException will be thrown.

setUserAgent

void setUserAgent(
    const std::string & userAgent
);

Sets the value of the User-Agent header sent with REST HTTP requests. If an empty string is given (default), no User-Agent header is included in the request.

setUsername

void setUsername(
    const std::string & username
);

Deprecated. This function issc_deprecated.

Sets the username for HTTP authentication.

Deprecated. Code should be changed to use setCredentials().

prepareRequest protected

void prepareRequest(
    const std::string & messageName
);

requireSession protected

const Poco::Net::HTTPClientSession & requireSession() const;

requireSession protected

Poco::Net::HTTPClientSession & requireSession();

Variables

CONTENT_TYPE static

static const std::string CONTENT_TYPE;

PROTOCOL static

static const std::string PROTOCOL;

BEARER protected static

static const std::string BEARER;

EMPTY protected static

static const std::string EMPTY;

USER_AGENT protected static

static const std::string USER_AGENT;

Securely control IoT edge devices from anywhere   Connect a Device