3.4. Proximie::PxRestApi reference

namespace PxRestApi

The PxRestApi namespace provides support for various common Proximie REST APIs, typically used to work with Proximie services.

The core class in this namespace is ProximieServices, which is used to make REST requests.

Whilst the REST APIs themselves use JSON payloads, PxRestApi support uses typed C++ structures. These payload structures are available in the PxRestApi namespace.

Note that the full REST APIs are extensive, and this namespace implements a smaller subset pertinent to functions typically required by SDK applications.

class Facility

#include <PxRestApi/Organisation.h>

Facility details

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

Facility ID.

std::string name

Facility name.

boost::optional<bool> isRemovable

If the facility is removable.

class Facilities

#include <PxRestApi/Organisation.h>

Facilities

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

boost::optional<std::vector<Facility>> facilities

List of facilities.

class Room

#include <PxRestApi/Organisation.h>

Room details

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

Room ID.

std::string name

Room name.

boost::optional<bool> isRemovable

If the room is removable.

class Rooms

#include <PxRestApi/Organisation.h>

Rooms

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

boost::optional<std::vector<Room>> rooms

List of rooms.

class OrganisationWithId

#include <PxRestApi/Organisation.h>

Organisation details

Public Functions

void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

Organisation ID.

std::string name

Organisation name.

std::string type

Organisation type.

std::string countryIso

Org country ISO code.

bool allowImageOverlay = {false}

Allow image overlay.

bool allowPublicVisibility = {false}

Allow public visibility.

bool allowRecording = {false}

Allows recording.

bool allowQuickReschedule = {false}

Allows quick reschedule.

bool allowStartNow = {false}

Allow start before scheduled time.

bool allowVideoSharing = {false}

Allows video sharing.

bool allowWearables = {false}

Allows wearables.

boost::optional<bool> allowAnalytics

Allow analytics.

boost::optional<bool> allowSessionCreation

Allow session creation (front-end)

class Organisations

#include <PxRestApi/Organisation.h>

Organisations

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

boost::optional<std::vector<OrganisationWithId>> organisations

List of organisations.

class Role

#include <PxRestApi/Organisation.h>

A role in an organisation

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string name

The name of the role in the organisation.

class OrganisationUserMember : public Proximie::PxRestApi::UserWithId

#include <PxRestApi/Organisation.h>

User as an organisation member

Public Functions

inline virtual void serialize(PxUtility::JsonSerializer &serializer) override

Serialize with JsonSerializer

Public Members

std::string invitedAt

When the user was invited (ISO8061)

std::vector<Role> roles

Roles the user has in the org.

class OrganisationMembers

#include <PxRestApi/Organisation.h>

Organisation members

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::vector<OrganisationUserMember> members

List of members.

class OrganisationMembership

#include <PxRestApi/Organisation.h>

Details of an organisation’s membership

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

Organisation ID.

std::string name

Organisation name.

std::string role

The role of the user in the organisation.

std::string invitedAt

When the user was invited (ISO8061)

class OrganisationUserMembership : public Proximie::PxRestApi::UserWithId

#include <PxRestApi/Organisation.h>

User with their membership in an organisation

Public Functions

inline virtual void serialize(PxUtility::JsonSerializer &serializer) override

Serialize with JsonSerializer

Public Members

boost::optional<std::vector<OrganisationMembership>> organisationMemberships

The organisation memberships.

class ProximieServices

#include <PxRestApi/ProximieServices.h>

A helper class to call certain Proximie REST APIs from SDK applications.

See Proximie REST services for details on creating and making ProximieServices objects in your applications.

Construction

ProximieServices(const shared_not_null<PxCore::ProximieContext> &context, ServiceSettings settings, RequestFields reqFields = {})

To create a ProximieServices object, we need a ProximieContext and service settings to use and request fields to apply to each request.

Interface

inline RequestFields &requestFields()

Access the fields used for each request. If the caller changes the values, they will be using in subsequent requests

User APIs

inline void getThisUser(const FetchHandler<OrganisationUserMembership> &handler) const

Get the details of the current user using a callback handler

See: https://docs.proximie.net/reference/getmyuser

inline FetchFuture<OrganisationUserMembership> getThisUser() const

Get the details of the current user as a future

See: https://docs.proximie.net/reference/getmyuser

inline void getSpecialities(const FetchHandler<Taxonomy> &handler) const

Get the specialities for the authorised user using a callback handler

See: https://docs.proximie.net/reference/getsessionspecialitiestaxonomy

inline FetchFuture<Taxonomy> getSpecialities() const

Get the specialities for the authorised user as a future

See: https://docs.proximie.net/reference/getsessionspecialitiestaxonomy

Organisation APIs

inline void getOrganisations(const FetchHandler<Organisations> &handler) const

Get all organisations that the authorised user is a member of using a callback handler

See: https://docs.proximie.net/reference/getorganisations

inline FetchFuture<Organisations> getOrganisations() const

Get all organisations that the authorised user is a member of as a future

See: https://docs.proximie.net/reference/getmembers

inline void getOrganisationMembers(string_view orgId, const FetchHandler<OrganisationMembers> &handler) const

Get all members for a given organisation using a callback handler

See: https://docs.proximie.net/reference/getmembers

inline FetchFuture<OrganisationMembers> getOrganisationMembers(string_view orgId) const

Get all members for a given organisation as a future

See: https://docs.proximie.net/reference/getmembers

inline void getFacilities(string_view orgId, const FetchHandler<Facilities> &handler) const

Get an organisation’s facilities using a callback handler

See: https://docs.proximie.net/reference/getfacilities

inline FetchFuture<Facilities> getFacilities(string_view orgId) const

Get an organisation’s facilities as a future

See: https://docs.proximie.net/reference/getfacilities

inline void getFacilityRooms(string_view orgId, string_view facilityId, const FetchHandler<Rooms> &handler) const

Get an organisation’s facility’s rooms using a callback handler

See: https://docs.proximie.net/reference/getrooms

inline FetchFuture<Rooms> getFacilityRooms(string_view orgId, string_view facilityId) const

Get an organisation’s facility’s rooms as a future

See: https://docs.proximie.net/reference/getrooms

inline void getNonRoomNotations(const FetchHandler<Rooms> &handler) const

Get available notations for “non-rooms” using a callback handler

Non-rooms are used when a room is unknown or N/A

See https://docs.proximie.net/reference/getnonroomnotationstaxonomy

inline FetchFuture<Rooms> getNonRoomNotations() const

Get available notations for “non-rooms” as a future

Non-rooms are used when a room is unknown or N/A

See https://docs.proximie.net/reference/getnonroomnotationstaxonomy

inline void createSession(string_view orgId, const CreateSessionRequest &session, const FetchHandler<CreateSessionResponse> &handler) const

Create a session in an organisation using a callback handler

See: https://docs.proximie.net/reference/createsession

inline FetchFuture<CreateSessionResponse> createSession(string_view orgId, const CreateSessionRequest &session) const

Create a session in an organisation as a future

See: https://docs.proximie.net/reference/createsession

Session APIs

inline void getSurgicalTypes(const FetchHandler<Taxonomy> &handler) const

Get the session surgical types available using a callback handler

See: https://docs.proximie.net/reference/getsurgicaltypestaxonomy

inline FetchFuture<Taxonomy> getSurgicalTypes() const

Get the session surgical types available as a future

See: https://docs.proximie.net/reference/getsurgicaltypestaxonomy

inline void getSessionAccesses(const FetchHandler<Taxonomy> &handler) const

Get the session access types available using a callback handler

See: https://docs.proximie.net/reference/getsessionaccessestaxonomy

inline FetchFuture<Taxonomy> getSessionAccesses() const

Get the session access types available as a future

See: https://docs.proximie.net/reference/getsessionaccessestaxonomy

inline void getSession(string_view sessionId, const FetchHandler<GetSessionResponse> &handler) const

Given a session ID, request the details for that session using a callback handler

See: https://docs.proximie.net/reference/getsession

inline FetchFuture<GetSessionResponse> getSession(string_view sessionId) const

Given a session ID, request the details for that session as a future

See: https://docs.proximie.net/reference/getsession

inline void getSessions(const FetchHandler<Sessions> &handler) const

Return all available sessions using a callback handler

See: https://docs.proximie.net/reference/getsessions

inline FetchFuture<Sessions> getSessions() const

Return all available sessions as a future

See: https://docs.proximie.net/reference/getsessions

inline void deleteSession(const FetchHandler<void> &handler, string_view sessionId) const

Delete a session using a callback handler

See: https://docs.proximie.net/reference/deletesession

inline FetchFuture<void> deleteSession(string_view sessionId) const

Delete a session as a future

See: https://docs.proximie.net/reference/deletesession

Stream APIs

inline void streamConnectionSettings(string_view streamId, const FetchHandler<SessionConnectionSettings> &handler) const

Given a media stream ID, return the connection settings to access that media session on the remote media server using a callback handler

inline FetchFuture<SessionConnectionSettings> streamConnectionSettings(string_view streamId) const

Given a media stream ID, return the connection settings to access that media session on the remote media server as a future

Public Types

enum class ApiVer

Proximie APIs are versioned for API updates and releases

Values:

enumerator v1

Legacy API.

enumerator v2

v2 is the latest API version

using HttpFetch = PxUtility::HttpFetch

ProximieServices uses the HTTP fetch utility

using RequestFields = HttpFetch::RequestFields

Request fields used for each request

template<typename T>
using PayloadResult = ProximieServicesDetail::PayloadResult<T>

A fetch result, typically with a typed payload value.

template<typename T>
using FetchHandler = std::function<void(const PayloadResult<T>&)>

The handler function signature for a typed fetch operation.

template<typename T>
using FetchFuture = std::future<PayloadResult<T>>

The future result of a typed fetch operation.

Public Functions

template<>
inline void parseTypedPayload(PayloadResult<void>&, const json_object*)

Specialization for void results, which have no payload.

struct ServiceSettings

#include <PxRestApi/ProximieServices.h>

Service settings that are used for all API calls for the object

Public Members

std::string host

Service host name, e.g. "my.proximie.net"

PxUtility::NetworkPort_t port = PxUtility::DEFAULT_SSL_PORT

Port to use when making requests By default this is set to the default SSL port for HTTP

class RestErrorDetail

#include <PxRestApi/RestError.h>

Error details for failed REST API requests

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

uint64_t statusCode = 0

HTTP status code.

std::string errorCode

Error code.

std::string message

Error message.

std::string timestamp

Timestamp of the error.

std::string version

Version of the API that returned the error.

boost::optional<std::string> correlationId

Correlation ID.

class RestError

#include <PxRestApi/RestError.h>

Error details for failed REST API requests

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

RestErrorDetail error

Error details.

class SessionOwner

#include <PxRestApi/Session.h>

Defines a session owner and their details

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

Unique id for the owner.

std::string name

Owner name.

std::string email

Owner email.

class SessionType

#include <PxRestApi/Session.h>

Defines the session type

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string name

The session type name.

double weighting = {0.0}

Weighting value.

class SessionAccess

#include <PxRestApi/Session.h>

Defines the session access type

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string name

The session access name.

class SessionParticipant

#include <PxRestApi/Session.h>

Defines a session’s participant

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

User id.

boost::optional<std::string> role

The participant’s role (optional)

class Session

#include <PxRestApi/Session.h>

A given session appointment details

Public Types

using Status = SessionStatus::Enum

Session status alias

Public Functions

inline bool statusIs(Status statusEnum) const

Helper to test the payload’s status (string) value

void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string title

The session name.

SessionOwner owner

Session owner object.

std::string scheduledAt

Scheduled date & time (ISO8601 format)

int64_t estimatedDuration = {0}

Duration (in milliseconds)

std::string createdAt

When created.

std::string updatedAt

When last updated.

SessionType type

Session type.

SessionAccess access

Session access.

std::string status

Session status.

boost::optional<std::string> description

Description (optional)

boost::optional<std::string> deletedAt

Deletion time (if deleted)

boost::optional<std::string> surgicalType

Per surgical type taxonomy

boost::optional<std::vector<SessionParticipant>> participants

List of participants.

class SessionWithUrlAndId

#include <PxRestApi/Session.h>

Full session details, including appointment, organisation and media session

Public Functions

void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

Session id.

boost::optional<Stream> stream

Media session details.

OrganisationWithId organisation

Organisation details.

Session session

Session appointment details.

class Sessions

#include <PxRestApi/Session.h>

Payload with a list of sessions

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::vector<SessionWithUrlAndId> sessions

List of sessions.

class GetSessionResponse

#include <PxRestApi/Session.h>

Response payload when requesting a session’s details

Public Functions

void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

Session id.

boost::optional<Session> session

Session details.

boost::optional<Stream> stream

Media session details.

boost::optional<Facility> facility

Facility details.

boost::optional<Room> room

Room details.

boost::optional<OrganisationWithId> organisation

Organisation.

class CreateSessionRequest

#include <PxRestApi/Session.h>

Request parameters for creating a session

Public Functions

void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string title

Name of the video session.

std::string scheduledAt

Data and time in ISO8601 format.

uint64_t estimatedDuration = 0

Duration in milliseconds.

std::string speciality

Per the speciality taxonomy.

std::string access

Per session access taxonomy.

std::string facility

UUID of the facility.

std::string room

UUID of the room.

boost::optional<std::string> surgicalType

Per surgical type taxonomy.

boost::optional<std::string> description

What the session is for.

boost::optional<std::string> owner

UUID of the session owner

boost::optional<std::vector<SessionParticipant>> participants

List of participants.

boost::optional<std::string> status

Session status, see SessionStatus for values.

class CreateSessionResponse

#include <PxRestApi/Session.h>

Response to a create session request

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

Session id.

Session session

Session details.

class SessionConnectionServer

#include <PxRestApi/SessionConnection.h>

Media server connection details

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string url

URL.

std::string httpUrl

HTTP URL.

std::string apiKey

API key to use to access the media server.

class IceServerSettings

#include <PxRestApi/SessionConnection.h>

ICE server settings

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string username

User name.

std::string credential

Credentials.

std::string urls

ICE URLs.

class CallStatsProxies

#include <PxRestApi/SessionConnection.h>

CallStats proxy details

Public Functions

void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string appSettingsUrl

App settings URL.

std::string authServiceUrl

Auth service URL.

std::string collectorUrl

Collector URL.

std::string csioInternalApiUrl

Callstats internal API URL.

std::string restEventUrl

REST event URL.

std::string restStatsUrl

REST stats URL.

std::string wsUrl

WebSocket URL.

class DcpBroker

#include <PxRestApi/SessionConnection.h>

Proximie DCP broker details

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string wssUrl

Secure WebSockets URL.

std::string mqttsUrl

Secure MQTT URL.

class SessionConnectionSettings

#include <PxRestApi/SessionConnection.h>

Details for a media session’s session, services and connection parameters

Public Functions

void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string startedAt

Start time.

std::string username

User name.

std::string credential

Credential details.

SessionConnectionServer audioServer

Audio media server connection.

SessionConnectionServer videoServer

Video media server connection.

std::vector<IceServerSettings> iceServers

ICE servers to use.

DcpBroker dcpHomeBroker

DCP ‘home’ broker details.

DcpBroker dcpSessionBroker

DCP broker for the session.

std::string newRelicLogUrl

NewRelic logging URL.

class SessionStatus

#include <PxRestApi/SessionStatus.h>

Helper class for session status strings.

Public Types

enum class Enum

Session status enumeration

Values:

enumerator SCHEDULED

Media session has been scheduled, but is not ready yet.

enumerator LAUNCHING

Media session is starting.

enumerator ACTIVE

Media session is available to join.

enumerator CLOSING

Media session is shutting down, joining is disallowed.

enumerator CLOSED

Media session has fully closed.

Public Static Functions

static string_view stringFrom(Enum statusEnum)

Helper to obtain the string representation from a status enumeration.

static inline bool statusIs(string_view statusString, Enum statusEnum)

Helper to test a status (string) value.

class Stream

#include <PxRestApi/Stream.h>

A media session stream’s details

Public Types

using Status = SessionStatus::Enum

Stream status alias

Public Functions

inline bool statusIs(Status statusEnum) const

Helper to test the payload’s status (string) value

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

Media stream ID.

std::string status

Media stream status (as string)

std::string url

Media stream URL.

class Taxonomy

#include <PxRestApi/Taxonomy.h>

Taxonomy details.

Public Functions

inline void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::vector<std::string> taxonomyTypes

Taxonomy types.

class UserWithId

#include <PxRestApi/User.h>

User details

Subclassed by Proximie::PxRestApi::OrganisationUserMember, Proximie::PxRestApi::OrganisationUserMembership

Public Functions

virtual void serialize(PxUtility::JsonSerializer &serializer)

Serialize with JsonSerializer

Public Members

std::string id

User UD.

std::string email

User’s email.

bool hasAcceptedTerms = {false}

If the terms have been accepted.

boost::optional<std::string> name

Full name of the user.

boost::optional<std::string> phone

User’s phone.

boost::optional<std::string> userTitle

User’s title.

boost::optional<std::string> speciality

User’s speciality.

boost::optional<std::string> countryIso

User’s Country (ISO 3166)

boost::optional<std::string> city

City of the user.

namespace ProximieServicesDetail

struct FetchResultBase

#include <PxRestApi/ProximieServices.h>

A base fetch result with no payload defined.

Subclassed by Proximie::PxRestApi::ProximieServicesDetail::PayloadResult< T >, Proximie::PxRestApi::ProximieServicesDetail::PayloadResult< void >

Public Functions

FetchResultBase() = default

Default constructor for base fetch results.

inline explicit FetchResultBase(const PxUtility::HttpFetch::FetchResult &result)

Construct a base fetch result from a general fetch result.

std::string errorSummary() const

Obtain an error summary string for a response If there is no error, returns an empty string

Public Members

error_code error

Error code for the fetch process.

std::shared_ptr<PxUtility::HttpFetch::FetchResponse> response

Underlying response details.

May be null in case of extreme fetch errors

std::shared_ptr<RestError> errorDetails

Additional error details if any.

Will be null if there is no error or no additional details

template<typename T>
struct PayloadResult : public Proximie::PxRestApi::ProximieServicesDetail::FetchResultBase

#include <PxRestApi/ProximieServices.h>

A fetch result with a typed payload.

Public Functions

FetchResultBase() = default

Default constructor for base fetch results.

inline explicit FetchResultBase(const PxUtility::HttpFetch::FetchResult &result)

Construct a base fetch result from a general fetch result.

Public Members

std::shared_ptr<T> payload

The payload serialized from the fetch response, if available.

Payload may be null:

• There was no expected resulting JSON to parse

• The fetch failed (check the error code)

• The payload could not be deserialized (check the error code)

template<>
struct PayloadResult<void> : public Proximie::PxRestApi::ProximieServicesDetail::FetchResultBase

Public Functions

FetchResultBase() = default

Default constructor for base fetch results.

inline explicit FetchResultBase(const PxUtility::HttpFetch::FetchResult &result)

Construct a base fetch result from a general fetch result.