5.2.7. Release notes for v0.5

0.5.1

FeedManager::onNewRemoteFeed now provides feed metadata to the callback in addition to the stream ID. The metadata includes the feed type and label (when provided).
Updated the Async operations & threading to explain how SDK threading works in more detail.
The PxMedia::MediaServerStreamId type, which was removed from the APIs in a previous release, incorrectly remained in the public headers. This is now no longer public, but if any existing code still refers to the type (e.g. with using or typedef) it will cause a compile-time error. You should remove any references to the MediaServerStreamId type from your code.

0.5.0

Promise/future support

Several of the SDK APIs now support returning std::future as well as the previous callback mechanism for asynchronous operations.

See the updated Async operations & threading section for full details.

Changes to ProximieContext (breaking changes)

One of the main changes in this release is to remove the ASIO io_context from ProximieContext. The application now only needs to create the context using it’s static create() method, supplying the SSL details as before.

Since the io_context is now managed internally, the application no longer needs to “pump” the context with called to restart and run.

Since the SDK now manages it’s own ASIO context internally, ProximieContext has no involvement in posting or dispatching tasks; hence the removal of the dispatch() and post() methods.

See the updated ProximieContext section for full details.

Changes to FeedManager (breaking changes)

FeedManager::connectToSession now returns a std::future rather than an outcome to allow for more flexible handling of the connection. The application can wait on the future to complete, or use a callback as before.

ProximieServices API changes to support future return (breaking changes)

ProximieServices now supports returning a std::future with an outcome type that holds either an error or the result. However, for consistency, the callback-based API handler signature now also takes a single “result” type which includes the error, rather than taking the error and result as two parameters.

Additionally, we have removed the “async” prefix from the member function names, for clarity and consistency.

Any previous application code using like this:

using Sessions = Proximie::PxRestApi::Sessions;
using ProximieServices = Proximie::PxRestApi::ProximieServices;

using Response = ProximieServices::PayloadResponse<Sessions>; // Before: PayloadResponse

auto callback = [](error_code error, const Response& response) {
  if (error) {
      // Handle error
  } else {
      auto sessions = response.payload; // Sessions object in the response
};
pxapi.asyncGetSessions(callback); // Before: async prefix to function name

Becomes:

using Result = ProximieServices::PayloadResult<Sessions>; // Now: PayloadResult

auto callback = [](const Result& result) {
  if (result.error) {
      // Handle error
  } else {
      auto sessions = result.payload; // Sessions object in the result
};
pxapi.getSessions(callback); // Now: no async prefix to function name

Or using a future instead of a callback:

auto result = pxapi.getSessions().get();  // Note: get() will block
if (result.error) {
    // Handle error
} else {
    auto sessions = result.payload; // Sessions object in the result
}

MakeRestRequest is replaced by HttpFetch (breaking changes)

The PxUtility::MakeRestRequest utility class has been replaced a new class HttpFetch which has a cleaner interface and supports std::future for asynchronous operations. There is also a HttpFetchTyped variant which can be used to automatically parse the response into a specific type.

The updated RequestParams and RequestFields types are similar but now use a builder pattern to chain-set their parameters, to be more consistent with other SDK property setting.

Any previous application code using MakeRestRequest like this:

MakeRestRequest::RequestParams request(verb, host, path, body); // Old: parameters in ctor
auto callback = [](error_code error, const MakeRestRequest::RequestResult& result) {
    // if (error) ...
};
MakeRestRequest(pxcontext, request, callback)();

May be replaced with code like this:

HttpFetch::FetchRequest request(pxcontext);
request.params.verb(verb).host(host).target(path).body(body); // New: chained setters
auto callback = [](HttpFetch::FetchResult result) {
    // if (result.error) ...
};
HttpFetch::fetch(request, callback);

Or use a future instead of a callback:

auto fetched = HttpFetch::fetch(request).get();  // Blocking call
if (fetched.error) {
    // ...

See the class documentation for HttpFetch for more details.

RestService API uses new HttpFetch types (breaking changes)

The RestService class previously used the PxUtility::MakeRestRequest utility class which has been replaced with HttpFetch as mentioned above.

If your application was using RestService, note:

The class constructor now provides the request fields as a HttpFetch::RequestFields value.
asyncRestCall() is now named request(), and takes a HttpFetch::RequestParams value.
request() can now return a future or take a callback handler.
request() can take a payload template type to automatically parse the response into a specific type using HttpFetchTyped.

Changes to SDK logging (some breaking changes)

See the updated SDK Logging section for full details.

Logging has been updated to use the internal SDK context to cleanly defer output handling to the application. This has required a few changes to the logging and how the application provides a delegate. For convenience, the logger now provides a default logging handler that writes to standard output/error.

Changes to the use of the PxLogger class:

The PxLogger class has moved to the PxCore namespace since it is used across the whole SDK. Any references will need to #include <PxCore/PxLogger.h> and use the PxCore namespace accordingly.
To better ensure the logger’s lifetime throughout the app and SDK, PxLogger’s get() method now returns a shared pointer. Application could should replace PxLogger::get(). (dot operator access) with PxLogger::get()-> (arrow operator).
Logging severity is now set on the PxLogger itself.

Changes to logging delegates

The logging delegate interface class LoggerBase is now PxLogger::ILoggerDelegate.
This class now only requires the handleLog() method to be implemented.
The signature of handleLog() now takes an additional parameter with supplementary details of the log message. This currently adds the timestamp rather than requiring the delegate to generate it.

Some logging elements have moved, whilst retaining the same functionality:

LogSeverity (previously defined in LoggerBase) has moved to PxLogger::LogSeverity.
Similarly, the logging helper functions such as PxLogger::severityLabel have been moved to PxLogger.

Note: The sample demo has been updated to reflect these changes.

Feature: SDK configuration options for media

There is now a PxMedia::Configuration object that can be used to configure the media SDK:

Programmatically set GStreamer debug levels (rather than using the GST_DEBUG environment variable)
GStreamer output target (console or SDK logger).
See PxMedia::Configuration documentation for more details.

Other changes

Minor change to the demo app to use the Proximie namespace, to improve clarity by removing numerous Proximie:: namespace prefixes.