1.4. Application development

1.4.1. Notes

The following sections assume the following #include directives and types:

#include <PxCore/ProximieContext.h>

using ProximieContext = Proximie::PxCore::ProximieContext;

1.4.2. SDK initialisation

1.4.3. Session selection (remote)

The SDK supports remote sessions with Proximie medias servers as well as local “peer sessions”. For more details on the latter, refer to the documentatio section on Peer Streaming.

In the remote case, an application can call on various Proximie REST APIs to list available sessions and get their details. The PxRestApi::ProximieServices class provides support for making Proximie REST API requests.

See the Proximie REST services section for extensive details, but the application will typically create a ProximieServices object, providing the ProximieContext, and other connection details and request fields to make requests.

    using ProximieServices = Proximie::PxRestApi::ProximieServices;

    ProximieServices::ServiceSettings service;
    service.host = "my.proximie.net";

    ProximieServices::RequestFields reqFields;
    reqFields.tokenProvider(auth);

    ProximieServices pxapi(pxcontext, service, reqFields);

Then, a list of available sessions can be obtained:

    SessionsResult result = pxapi.getSessions().get();  // Note: get() will block
    if (result.error) {
        // Handle error
    } else {
        // The result contains a response with a typed payload
        std::shared_ptr<Sessions> sessionsPayload = result.payload;

        // ...
    }

Assuming there are no errors, the response returns a Proximie::PxRestApi::Sessions object, which contains a vector of session detail objects of type SessionWithUrlAndId. Aside from the session’s appointment details (such as session title, owner, participants, etc.), the stream data member contains details of the media session that can be connected to.

We need to check a given stream to see if it’s available. Each stream has a status (see Stream::Status) which can be examined. See the documentation for details, but essentially only ACTIVE sessions are available for joining.

    using Session = Proximie::PxRestApi::Session;

    for (const auto& item : sessionsPayload->sessions) {
        const auto& session = item.session;
        if (session.statusIs(Session::Status::ACTIVE)) {
            // Display to user as something that can be joined...
        } else if (session.statusIs(Session::Status::SCHEDULED) ||
                   session.statusIs(Session::Status::LAUNCHING)) {
            // Display to user as a forthcoming session...
        } else {
            // Session not available (closed etc.)
        }
    }

Given a session with a stream that is available (i.e. ACTIVE), the application can then start a media session with it using the PxMedia::MediaServerSession.

1.4.4. Start a session with a MediaServerSession

The MediaServerSession manages a media session for the application. Media servers sessions are simply created with a Proximie::PxCore::ProximieContext as described in Creating a MediaServerSession instance.

Then, given the session details (typically the session ID as described above), the session object can join the Proximie session as described in Connecting to a media session.

1.4.5. Manage media feeds in the session

Once the media server session is attached to the Proximie session, the application can share audio and video feeds with other participants. How to start, receive, and stop media feeds is all covered in the section on Managing feeds.

For more details on using the MediaServerSession class, see Media Server Session.

1.4.6. Error handling

The application needs to handle errors that may occur during the above processes. Errors can occur with individual feeds, or with the session itself (e.g. internet connection issues).

See Session error handling for details on error handling in your application.

1.4.7. Other application features

Once the application handles the core functionality described above, you may want to review the other features available in the SDK, which are covered in more detail in SDK features, such as Adaptive Streaming and Peer Streaming.