Provides AWS endpoint information. More...

Collaboration diagram for AwsEndpoint:

Public Types
enum	Transport { HTTP = 0x01, HTTPS = 0x02, SMTP = 0x04, AnyTransport = HTTP\|HTTPS\|SMTP }
	Network transport supported by one or more AWS endpoints.

Public Member Functions
	AwsEndpoint (const QByteArray &hostName)
	Constructs a new AwsEndpoint object. More...

	AwsEndpoint (const QString &hostName)
	Constructs a new AwsEndpoint object. More...

	~AwsEndpoint ()
	AwsEndpoint destructor.

bool	isSupported (const Transport transport) const
	Is the given transport supported by this endpoint? More...

bool	isValid () const
	Is this endpoint valid? More...

QString	fullServiceName () const
	Get this endpoint's full service name. More...

QString	hostName () const
	Get the name of host represented by this endpoint. More...

QString	regionName () const
	Get this endpoint's primary region name. More...

QString	serviceName () const
	Get this endpoint's service name. More...

QStringList	supportedRegions (const Transports transport=AnyTransport) const
	Get the full list of regions this endpoint supports. More...

Static Public Member Functions
static QUrl	getEndpoint (const QString &regionName, const QString &serviceName, const Transports transport=AnyTransport)
	Get a QUrl for an AWS endpoint. More...

static bool	isSupported (const QString &regionName, const QString &serviceName, const Transports transport=AnyTransport)
	Is a region / service / transport combination supported by Amazon? More...

static QString	fullServiceName (const QString &serviceName)
	Get the full name for given service. More...

static QStringList	supportedRegions (const QString &serviceName, const Transports transport=AnyTransport)
	Get a list of regions that supported for a given service. More...

static QStringList	supportedServices (const QString &regionName, const Transports transport=AnyTransport)
	Get a list of services that support a given region. More...

Private Attributes
AwsEndpointPrivate *const	d_ptr
	Internal d-pointer.

Friends
class	TestAwsEndpoint

Detailed Description

Provides AWS endpoint information.

Note: This class provides fairly low-level access to AWS endpoint data. You should consider using the AwsRegion and/or various AwsService-derived classes in preference to using this class directly where possible.

This class parses the endpoint.xml data available at http://aws-sdk-configurations.amazonwebservices.com/endpoints.xml

The endpoint.xml file is embedded as a resource in the libqtaws library - not fetched remotely at runtime.

Example usage:

AwsEndpoint endpoint(QLatin1String("cloudformation.us-east-1.amazonaws.com"));
endpoint.hostName();    // "cloudformation.us-east-1.amazonaws.com"
endpoint.regionName();  // "us-east-1"
endpoint.serviceName(); // "cloudformation"
endpoint.supportedRegions(); // [ "us-east-1" ]
endpoint.isSupported(AwsEndpoint::HTTP);  // false
endpoint.isSupported(AwsEndpoint::HTTPS); // true
QUrl ec2 = AwsEndpoint::getEndpoint("ap-southeast-2", "ec2");
QUrl iam = AwsEndpoint::getEndpoint("ap-southeast-2", "iam");
ec2.host(); // "ec2.ap-southeast-2.amazonaws.com"
iam.host(); // "iam.amazonaws.com"

See also: AwsRegion; AwsService

Definition at line 33 of file awsendpoint.h.

Constructor & Destructor Documentation

AwsEndpoint::AwsEndpoint ( const QByteArray & hostName )

Constructs a new AwsEndpoint object.

Parameters

hostName Name of an AWS host, encoded as UTF-8.

Definition at line 74 of file awsendpoint.cpp.

References AwsEndpointPrivate::hosts, and AwsEndpointPrivate::mutex.

     : d_ptr(new AwsEndpointPrivate(this))
 {
     Q_D(AwsEndpoint);
     d->hostName = QString::fromUtf8(hostName);
     QMutexLocker locker(&AwsEndpointPrivate::mutex);
     if (AwsEndpointPrivate::hosts.contains(d->hostName)) {
         if (!AwsEndpointPrivate::hosts[d->hostName].regionNames.empty()) {
             d->regionName = AwsEndpointPrivate::hosts[d->hostName].regionNames.first();
         }
         d->serviceName = AwsEndpointPrivate::hosts[d->hostName].serviceName;
     }
 }

AwsEndpoint::AwsEndpoint ( const QString & hostName )

Constructs a new AwsEndpoint object.

Parameters

hostName Name of an AWS host.

Definition at line 93 of file awsendpoint.cpp.

References hostName(), AwsEndpointPrivate::hosts, and AwsEndpointPrivate::mutex.

     : d_ptr(new AwsEndpointPrivate(this))
 {
     Q_D(AwsEndpoint);
     d->hostName = hostName;
     QMutexLocker locker(&AwsEndpointPrivate::mutex);
     if (AwsEndpointPrivate::hosts.contains(d->hostName)) {
         if (!AwsEndpointPrivate::hosts[d->hostName].regionNames.empty()) {
             d->regionName = AwsEndpointPrivate::hosts[d->hostName].regionNames.first();
         }
         d->serviceName = AwsEndpointPrivate::hosts[d->hostName].serviceName;
     }
 }

Member Function Documentation

QString AwsEndpoint::fullServiceName ( ) const

Get this endpoint's full service name.

The full service name is a human-readbale form. For example, the full name for the cloudsearch service is Amazon CloudSearch. Likewise, the full name for the rds service is Amazon Relational Database Service.

Returns: This endpoint's full service name.

See also: serviceName

Definition at line 262 of file awsendpoint.cpp.

References serviceName().

 {
     return fullServiceName(serviceName());
 }

QString AwsEndpoint::fullServiceName ( const QString & serviceName )

static

Get the full name for given service.

The full service name is a human-readbale form. For example, the full name for the cloudsearch service is Amazon CloudSearch. Likewise, the full name for the rds service is Amazon Relational Database Service.

Parameters

serviceName Canonical AWS service name to get the full name of.

Returns: This endpoint's full service name.

See also: serviceName

Definition at line 280 of file awsendpoint.cpp.

References AwsEndpointPrivate::loadEndpointData(), AwsEndpointPrivate::mutex, and AwsEndpointPrivate::services.

 {
     AwsEndpointPrivate::loadEndpointData();
     QMutexLocker locker(&AwsEndpointPrivate::mutex);
     const QHash<QString, AwsEndpointPrivate::ServiceInfo>::const_iterator
             service = AwsEndpointPrivate::services.constFind(serviceName);
     return (service == AwsEndpointPrivate::services.constEnd()) ? QString() : service.value().fullName;
 }

QUrl AwsEndpoint::getEndpoint	(	const QString &	regionName,
		const QString &	serviceName,
		const Transports	transport = `AnyTransport`
	)

static

Get a QUrl for an AWS endpoint.

This function will return a QUrl object for accessing an AWS service. The region and service names must match those used by Amazon.

If the specified region and/or service are not known to be valid for AWS, or the service is not supported in the specified region, then an invalid QUrl will be returned.

Note: An invalid QUrl is one for which QUrl::isValid returns false.

The transport parameter may be used to specify one or more transports to consider. If the specified AWS endpoint exists, but does not support //any// of the given transports, then an invalid QUrl is returned.

Where it makes sense to do so, the resulting QUrl's scheme will be set according to the requested transport. For example, if the selected transport is AwsEndpoint::HTTPS, then the resulting QUrl's schems will be set to "https".

If transport includes both AwsEndpoint::HTTP //and// AwsEndpoint::HTTPS, and both are supported by the AWS endpoint, then "https" will be chosed in preference to "http".

Note: It is possible for the returned QUrl to specify a host that is not located in, nor dedicated to the specified region. For examepl, if requesting an endpoint for the iam service in ap-southeast-2, the return endpoint is for a host (iam.amazonaws.com) which provides the ami services for all regions, not just ap-southeast-2. Services known to behave like this include: cloudfront, iam, importexport, route53, and sts.

Example usage:

QUrl ec2 = AwsEndpoint::getEndpoint("ap-southeast-2", "ec2");
QUrl iam = AwsEndpoint::getEndpoint("ap-southeast-2", "iam");
ec2.host(); // "ec2.ap-southeast-2.amazonaws.com"
iam.host(); // "iam.amazonaws.com"

Parameters

regionName	Endpoint's region name.
serviceName	Endpoint's service name.
transport	Optional network transport(s) for the endpoint.

Returns: A QUrl representing the AWS endpoint, or an invalid QUrl if there is no such known AWS endpoint.

Todo:: Handle SMTP here?

Definition at line 163 of file awsendpoint.cpp.

References AwsEndpointPrivate::RegionEndpointInfo::hostName, AwsEndpointPrivate::loadEndpointData(), AwsEndpointPrivate::mutex, regionName(), AwsEndpointPrivate::regions, serviceName(), and AwsEndpointPrivate::RegionEndpointInfo::transports.

Referenced by AwsRegion::hostName().

 {
     AwsEndpointPrivate::loadEndpointData();
     QMutexLocker locker(&AwsEndpointPrivate::mutex);
     if ((!AwsEndpointPrivate::regions.contains(regionName)) ||
         (!AwsEndpointPrivate::regions[regionName].services.contains(serviceName))) {
         return QUrl();
     }
     const AwsEndpointPrivate::RegionEndpointInfo &endpointInfo =
         AwsEndpointPrivate::regions[regionName].services[serviceName];
     if (!(endpointInfo.transports & transport)) {
         return QUrl();
     }
 
     QUrl url;
     url.setHost(endpointInfo.hostName);
     if ((endpointInfo.transports & HTTPS) && (transport & HTTPS))
         url.setScheme(QLatin1String("https"));
     else if ((endpointInfo.transports & HTTP) && (transport & HTTP))
         url.setScheme(QLatin1String("http"));
     /// @todo  Handle SMTP here?
     return url;
 }

QString AwsEndpoint::hostName ( ) const

Get the name of host represented by this endpoint.

Returns: Name of host represented by this endpoint.

Definition at line 193 of file awsendpoint.cpp.

Referenced by AwsEndpoint(), and isValid().

 {
     Q_D(const AwsEndpoint);
     return d->hostName;
 }

bool AwsEndpoint::isSupported	(	const QString &	regionName,
		const QString &	serviceName,
		const Transports	transport = `AnyTransport`
	)

static

Is a region / service / transport combination supported by Amazon?

Parameters

regionName	AWS region name to check support for.
serviceName	AWS service name to check support for.
transport	Optional transport to check support for.

Returns: true if the service is supported in the regionName region for at least one of the specified transports, false otherwise.

Definition at line 209 of file awsendpoint.cpp.

References AwsEndpointPrivate::loadEndpointData(), AwsEndpointPrivate::mutex, and AwsEndpointPrivate::regions.

Referenced by isSupported(), and AwsRegion::isSupported().

 {
     AwsEndpointPrivate::loadEndpointData();
     QMutexLocker locker(&AwsEndpointPrivate::mutex);
     return ((AwsEndpointPrivate::regions.contains(regionName)) &&
             (AwsEndpointPrivate::regions[regionName].services.contains(serviceName)) &&
             (AwsEndpointPrivate::regions[regionName].services[serviceName].transports & transport));
 }

bool AwsEndpoint::isSupported ( const Transport transport ) const

Is the given transport supported by this endpoint?

Parameters

transport Transport to check for support for.

Returns: true if the transport is supported by this endpoint, false otherwise.

Definition at line 225 of file awsendpoint.cpp.

References isSupported(), regionName(), and serviceName().

 {
     return isSupported(regionName(), serviceName(), AwsEndpoint::Transports(transport));
 }

bool AwsEndpoint::isValid ( ) const

Is this endpoint valid?

An endpoint is considered valid if the host specified during construction is a known AWS host, and thus we know what region and service(s) it supports.

For example:

AwsEndpoint good(QLatin1String("cloudformation.us-east-1.amazonaws.com"));
AwsEndpoint bad(QLatin1String("example.com"));
Q_ASSERT(good.isValid()); // good is valid.
Q_ASSERT(!bad.isValid()); // bad is not.

Returns: true if this endpoint is valid, false otherwise.

Definition at line 246 of file awsendpoint.cpp.

References hostName(), regionName(), and serviceName().

 {
     return ((!hostName().isEmpty()) && (!regionName().isEmpty()) && (!serviceName().isEmpty()));
 }

QString AwsEndpoint::regionName ( ) const

Get this endpoint's primary region name.

It is possible for a single endpiont to support multuple regions, such as iam.amazonaws.com, which provides the ami servive for all (non-government) regions.

In these cases, this function returns the primary region in which the service is located. The AwsEndpoint::supportedRegions function may be used to fetch the full list of regions this endpoint supports.

Returns: This endpoint's region name.

See also: supportedRegions

Definition at line 304 of file awsendpoint.cpp.

Referenced by getEndpoint(), isSupported(), isValid(), supportedRegions(), and supportedServices().

 {
     Q_D(const AwsEndpoint);
     return d->regionName;
 }

QString AwsEndpoint::serviceName ( ) const

Get this endpoint's service name.

Returns: This endpoint's service name.

See also: fullServiceName

Definition at line 317 of file awsendpoint.cpp.

Referenced by fullServiceName(), getEndpoint(), isSupported(), isValid(), and supportedRegions().

 {
     Q_D(const AwsEndpoint);
     return d->serviceName;
 }

QStringList AwsEndpoint::supportedRegions ( const Transports transport = AnyTransport ) const

Get the full list of regions this endpoint supports.

Alternatvely, AwsEndpoint::regionName may be used to get this endpoint's primary region.

Parameters

transport Optional transport to check for support.

Returns: A list of all regions this endpoint supports for //at least one// of the specified transports.

See also: regionName

Definition at line 336 of file awsendpoint.cpp.

References serviceName().

 {
     return supportedRegions(serviceName(), transport);
 }

QStringList AwsEndpoint::supportedRegions	(	const QString &	serviceName,
		const Transports	transport = `AnyTransport`
	)

static

Get a list of regions that supported for a given service.

Parameters

serviceName	AWS service to get the supported regions for.
transport	Optional transport(s) to check for support.

Returns: A list of AWS regions supported for the given service, for at least one of the specified transports.

Definition at line 350 of file awsendpoint.cpp.

References AwsEndpointPrivate::loadEndpointData(), AwsEndpointPrivate::mutex, regionName(), AwsEndpointPrivate::regions, serviceName(), and AwsEndpointPrivate::services.

 {
     AwsEndpointPrivate::loadEndpointData();
     QMutexLocker locker(&AwsEndpointPrivate::mutex);
 
     if (transport == AnyTransport) {
         return AwsEndpointPrivate::services[serviceName].regionNames;
     }
 
     QStringList regions;
     foreach (const QString &regionName, AwsEndpointPrivate::services[serviceName].regionNames) {
         if (AwsEndpointPrivate::regions[regionName].services[serviceName].transports & transport)
             regions.append(regionName);
     }
     return regions;
 }

QStringList AwsEndpoint::supportedServices	(	const QString &	regionName,
		const Transports	transport = `AnyTransport`
	)

static

Get a list of services that support a given region.

Parameters

regionName	AWS region to get the supported services for.
transport	Optional transport(s) to check for support.

Returns: A list of AWS services supported for the given region, for at least one of the specified transports.

Definition at line 376 of file awsendpoint.cpp.

References AwsEndpointPrivate::loadEndpointData(), AwsEndpointPrivate::mutex, regionName(), and AwsEndpointPrivate::regions.

Referenced by AwsRegion::supportedServices().

 {
     AwsEndpointPrivate::loadEndpointData();
     QMutexLocker locker(&AwsEndpointPrivate::mutex);
 
     if (transport == AnyTransport) {
         return AwsEndpointPrivate::regions[regionName].services.keys();
     }
 
     QStringList serviceNames;
     const AwsEndpointPrivate::RegionServices &services = AwsEndpointPrivate::regions[regionName].services;
     for (AwsEndpointPrivate::RegionServices::const_iterator iter = services.constBegin(); iter != services.constEnd(); ++iter) {
         if (iter.value().transports & transport)
             serviceNames.append(iter.key());
     }
     return serviceNames;
 }

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

core/awsendpoint.h
core/awsendpoint.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation