3.2. Proximie::PxCore reference

namespace PxCore

The PxCore namespace contains fundamental types, definitions and classes used throughout the Proximie SDK.

class ProximieContext

#include <PxCore/ProximieContext.h>

Provides key settings, services and functionality for components and classes throughout the Proximie SDK.

An application will typically create a ProximieContext at initialisation time, and provide it to other SDK objects as and when they are created.

Aliases

using ssl_context = boost::asio::ssl::context: See boost::asio::ssl::context

Creation

ProximityContext objects are created using the static create methods, which return shared pointers that are passed to other SDK objects.

static inline shared_not_null<ProximieContext> createNoSsl(): Create a Proximie content with no SSL support

static inline shared_not_null<ProximieContext> create(): Create a ProximieContext with a default SSL context

static shared_not_null<ProximieContext> create(std::shared_ptr<ssl_context> sslContext): Create a ProximieContext with a provided SSL context

static inline shared_not_null<ProximieContext> create(string_view sslCertPath): Convenience creation of a ProximieContext with a path to the SSL certificates, which is used to create an SSL context using PxUtility::makeSslContext

SSL context managed by the ProximieContext

inline bool hasSslContext() const: Check whether the ProximieContext has an SSL context

inline ssl_context &sslContext() const

Obtain the SSL context managed by the ProximieContext

It is an error to obtain the SSL context if none was supplied when the ProximieContext was created. Callers may check using ProximieContext::hasSslContext.

User agent string

The ProximieContext defines the default user agent string used when the SDK makes HTTP calls. If not set by the application, a default SDK user agent string is used.

inline const char *userAgent() const: Obtain the current user agent string

inline void setUserAgent(string_view prefix): Set the current user agent string

UUID generation

boost::uuids::uuid uuid() const: Generate a UUID value

std::string uuidStr() const: Generate a UUID as a string value

class PxLogger

#include <PxCore/PxLogger.h>

The SDK logger, which allows an application-provided delegate to handle logging output from the SDK.

To handle SDK logging output in the client application, the application may provide a delegate to the PxLogger instance. See SDK Logging for a guide on implementing a logging delegate in your application.

Logger access and delegation

static std::shared_ptr<PxLogger> get(): Provide access to the PxLogger instance

inline void setDelegate(std::shared_ptr<ILoggerDelegate> delegate): Sets the delegate logging handler for SDK logging

inline void setDelegate(std::shared_ptr<ILoggerDelegate> delegate, LogSeverity severityLevel): Sets the delegate logging handler, with severity level, for SDK logging.

void useStdOutputDelegate(): Sets the logging delegate to use standard outputs

inline void useStdOutputDelegate(LogSeverity withSeverity): Sets the logging delegate, with severity level, to use standard outputs.

inline void severityLevel(LogSeverity level): Set the current logger severity level

Logging output helpers

The following helpers are all static members of the class, for ease of use in logging delegates.

static const char *severityLabel(LogSeverity sev): Return a human-readable string for a given severity level

static std::string escapeFormat(const char *message): Format a given message with escapes

static inline std::string timestamp(): Returns a timestamp string for the current time

static inline std::string timestamp(const TimestampType &when): Returns a timestamp string for a given timestamp

Logging functions

inline bool testSeverity(LogSeverity level) const: The logger can be asked whether a given severity is of interest. Callers can call this function to check before going ahead with building the message to be logged out (e.g. if this is a non-trivial operation).

void log(LogSeverity level, const char *message): Log the message string if the severity is high enough

inline void log(LogSeverity level, const std::string &message): Log the message string if the severity is high enough

inline void log(LogSeverity level, const LogStream &stream)

Log a message provided by a LogStream, if the severity is high enough.

The stream is only used/referenced after checking the severity

inline void log(LogSeverity level, const std::function<std::string()> &lazy)

Lazy-evaluation logging, where the severity is checked before obtaining the message string value.

The lazy evaluation function is only called if the given severity is high enough

Parameters:

level – Log level for the message
lazy – A functor to return the message content

inline void log(LogSeverity level, const std::function<void(LogStream&)> &lazy)

Lazy-evaluation logging, where the severity is checked before obtaining the message content into a LogStream.

The lazy evaluation function is only called if the given severity is high enough

Parameters:

level – Log level for the message
lazy – A functor that takes the LogStream to set the message into

Public Types

enum class LogSeverity

Severity levels ranging from least severe to most.

Values can easily be compared with relational operators, e.g.:

if (severity >= LogSeverity::INFO) ...

Values:

enumerator TRACE: Trace logging.

enumerator DEBUG: Debug logging.

enumerator INFO: Informational logging.

enumerator WARNING: Warning logging.

enumerator ERROR: Error logging.

enumerator FATAL: Fatal error logging.

using LogStream = std::ostringstream: LogStream is an alias to output string stream

using TimestampType = boost::posix_time::ptime: Time type for timestamps

using TimestampClock = boost::date_time::microsec_clock<TimestampType>: Clock type for timestamps

class ILoggerDelegate

#include <PxCore/PxLogger.h>

The interface required by a logging delegate.

Public Functions

virtual void handleLog(LogSeverity level, const char *message, const LogMeta &data) = 0: The implementation of this function should handle the logging output for the application. The log level is provided to allow the delegate to customise its output and/or targets.

struct LogMeta

#include <PxCore/PxLogger.h>

Contains additional logging metadata that the logging delegate may use.

Public Members

TimestampType timestamp: Timestamp for the log message.

class PxSdkVersion

#include <PxCore/PxSdkVersion.h>

The version of the Proximie SDK, following the Semantic Versioning convention.

Version interface

static SemVer semver(): Obtain the current SDK version as a SemVer value.

static const char *version(): Obtain the current SDK version as a string.

struct SemVer

#include <PxCore/PxSdkVersion.h>

A semantic versioning version with MAJOR.MINOR.PATCH version elements.

Public Members

int32_t major: Major version number.

int32_t minor: Minor version number.

int32_t patch: Patch version number.

struct RemoteEnvironment

#include <PxCore/RemoteEnvironment.h>

Details for connecting to a remote Proximie services environment.

Helpers

static std::string replaceUrlPattern(string_view pattern, string_view value)

Helper to replace a single {} in a given pattern string.

Parameters:

pattern – Source pattern, with a {} to be replaced.
value – The value to replace the {} token with.

Returns:

A string where the pattern’s {} was replaced with the value.

Public Members

std::string sessionHost: Base host for sessions - e.g. live.proximie.net.

std::string globalApi: Host for global Proximie service APIs - e.g. my.proximie.net

std::string regionalApi

Host pattern for regional service API calls - e.g. {}.proximie.net

The regional host pattern, where {} is replaced with the region at runtime.

class SdkPimplWrapperBase

#include <PxCore/SdkPimplWrapper.h>

Base support for SdkPimplWrappers, which are used to reference objects that are implemented and owned by the SDK, and must only be accessed on the SDK context.

Subclassed by Proximie::PxCore::SdkPimplWrapper< MediaServerSessionImpl >, Proximie::PxCore::SdkPimplWrapper< PeerSessionImpl >, Proximie::PxCore::SdkPimplWrapper< MediaServerOutgoingVideoFeedImpl >, Proximie::PxCore::SdkPimplWrapper< FeedQualityMonitorImpl >, Proximie::PxCore::SdkPimplWrapper< AVOutputFeedFileImpl >, Proximie::PxCore::SdkPimplWrapper< T >

Public Functions

bool runningInSdkTaskThread() const: If the current thread is the SDK’s task thread, i.e. we can access the reference safely.

template<typename T> class SdkPimplWrapper : public Proximie::PxCore::SdkPimplWrapperBase 

#include <PxCore/SdkPimplWrapper.h>

A typed reference to an object that is implemented and owned by the SDK and must only be accessed on the SDK task context.

Public Functions

inline explicit SdkPimplWrapper(const shared_not_null<T> &ref): Create the pimpl reference from a given value

inline T &accessImmediate(): Directly access the reference, but must be on the SDK task thread

inline const T &accessImmediate() const: Directly access the reference, but must be on the SDK task thread

inline shared_not_null<T> accessImmediatePtr(): Obtain a non-null pointer reference to the object, but only when on the SDK task thread. Callers must only use/store the reference for use on the SDK task thread.

inline void accessPosted(std::function<void(T&)> work)

Post some work onto the SDK task context that uses the reference.

The work is “fire and forget”, and no result is returned. May be called from any thread, but is always “posted” and never called immediately.

inline void accessPosted(std::function<void(const T&)> work) const

Post some work onto the SDK task context that uses the reference.

The work is “fire and forget”, and no result is returned. May be called from any thread, but is always “posted” and never called immediately.

template<typename R> inline R accessSyncWait(const std::function<R(T&)> &work)

Provides the reference to the function, and calls it on the SDK task context safely, and returns the result synchronously to the caller.

May be called from any thread, and will block until the work is done.

If called from the SDK thread, the function is invoked directly and result returned immediately.
If called from another thread, the function is posted to the SDK thread and the calling thread blocked until the result is returned.

template<typename R> inline R accessSyncWait(const std::function<R(const T&)> &work) const

Provides the reference to the function, and calls it on the SDK task context safely, and returns the result synchronously to the caller.

May be called from any thread, and will block until the work is done.

If called from the SDK thread, the function is invoked directly and result returned immediately.
If called from another thread, the function is posted to the SDK thread and the calling thread blocked until the result is returned.