Class RenderingSession

Each rendering session is running on a dedicated server, providing the Azure Remote Rendering functionality.

An application can manage multiple RenderingSession objects. However, each application can only connect a single RenderingSession for rendering.

class Microsoft::Azure::RemoteRendering::RenderingSession final

Methods

ConnectAsync

Connect to the runtime on the server associated with this session.

auto ConnectAsync(Microsoft::Azure::RemoteRendering::RendererInitOptions initOptions, std::function<void(Status, Microsoft::Azure::RemoteRendering::ConnectionStatus)> callback) -> void;

Parameters

Name Type Description
initOptions RendererInitOptions Connection parameters.
  • callback - A task with a result of the new connection status. The returned task will complete in the RenderingConnection.Update tick.

Returns

Type Description
void A task with a result of the new connection status. The returned task will complete in the RenderingConnection.Update tick.

ConnectToArrInspectorAsync

Gets a file path pointing to an HTML file to connect to the ArrInspector website.

The ArrInspector provides introspection and service status updates.

auto ConnectToArrInspectorAsync(std::function<void(Status, std::string)> callback) -> void;

Parameters

Name Type Description
  • callback - The location of a local HTML page to load the ArrInspector. The returned task will complete in an arbitrary thread.

Returns

Type Description
void The location of a local HTML page to load the ArrInspector. The returned task will complete in an arbitrary thread.

See also

Disconnect

Disconnect this session if connected to the runtime.

auto Disconnect() noexcept -> Microsoft::Azure::RemoteRendering::Result;

Returns

Type Description
Result Result.Success, Result.NotInitialized, Result.Fail, Result.NoConnection

GetPropertiesAsync

Queries the properties of the session (hostname, lease time, size, etc).

Since the underlying call is a REST call, there should be sufficient delay (5-10s) between subsequent calls to avoid server throttling. In case of throttling, the function will fail and the HttpResponseCode reports code 429 ("too many requests").

  • A Result.InvalidParam error occurs if the rendering service URL was empty, because the account domain and account Id was not provided.
  • A Result.SessionNotFound error occurs if the corresponding session could not be found. Please check the provided session Id.
  • A Result.AuthenticationFailed error occurs if the request could not be authenticated.
  • A Result.NotInitialized error occurs if the RemoteRenderingClient was not initialized.
  • A Result.TooManyRequests error occurs if the rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
  • A Result.DomainUnreachable error occurs if remote rendering domain is unreachable. Url may be invalid or Azure Remote Rendering is not supported in this region.
  • A Result.ConnectionRefused error occurs if remote rendering connection is refused by destination host.
  • A Result.ConnectionFailed error occurs if remote rendering connection failed. Exact reason is unknown.
  • A Result.Timeout error occurs if remote rendering connection timed out.
auto GetPropertiesAsync(std::function<void(Status, ApiHandle<Microsoft::Azure::RemoteRendering::RenderingSessionPropertiesResult>)> callback) -> void;

Parameters

Name Type Description
  • callback - Session properties or an error context. The returned task will complete in an arbitrary thread.

Returns

Type Description
void Session properties or an error context. The returned task will complete in an arbitrary thread.

RenewAsync

Updates the session parameters for this rendering session.

See RenderingSessionUpdateOptions for details.

Since the underlying call is a REST call, there should be sufficient delay (5-10s) between subsequent calls to avoid server throttling. In case of throttling, the function will fail and the HttpResponseCode reports code 429 ("too many requests").

  • A Result.InvalidParam error occurs if the rendering service URL was empty, because the account domain and account Id was not provided, or if the maxLeaseTimeMinutes value was invalid. It has to be bigger than the current value of maxLeaseTimeMinutes.
  • A Result.AuthenticationFailed error occurs if the request could not be authenticated.
  • A Result.NotInitialized error occurs if the RemoteRenderingClient was not initialized.
  • A Result.TooManyRequests error occurs if the rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
  • A Result.DomainUnreachable error occurs if remote rendering domain is unreachable. Url may be invalid or Azure Remote Rendering is not supported in this region.
  • A Result.ConnectionRefused error occurs if remote rendering connection is refused by destination host.
  • A Result.ConnectionFailed error occurs if remote rendering connection failed. Exact reason is unknown.
  • A Result.Timeout error occurs if remote rendering connection timed out.
auto RenewAsync(Microsoft::Azure::RemoteRendering::RenderingSessionUpdateOptions updateOptions, std::function<void(Status, ApiHandle<Microsoft::Azure::RemoteRendering::SessionContextResult>)> callback) -> void;

Parameters

Name Type Description
updateOptions RenderingSessionUpdateOptions The new parameters to use
  • callback - A task with a result context containing success information. The returned task will complete in an arbitrary thread.

Returns

Type Description
void A task with a result context containing success information. The returned task will complete in an arbitrary thread.

StopAsync

Stops the Azure session. It is not possible to connect to this session again.

  • A Result.InvalidParam error occurs if the rendering service URL was empty, because the account domain and account Id was not provided.
  • A Result.AuthenticationFailed error occurs if the request could not be authenticated.
  • A Result.NotInitialized error occurs if the RemoteRenderingClient was not initialized.
  • A Result.TooManyRequests error occurs if the rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
  • A Result.DomainUnreachable error occurs if remote rendering domain is unreachable. Url may be invalid or Azure Remote Rendering is not supported in this region.
  • A Result.ConnectionRefused error occurs if remote rendering connection is refused by destination host.
  • A Result.ConnectionFailed error occurs if remote rendering connection failed. Exact reason is unknown.
  • A Result.Timeout error occurs if remote rendering connection timed out.
auto StopAsync(std::function<void(Status, ApiHandle<Microsoft::Azure::RemoteRendering::SessionContextResult>)> callback) -> void;

Parameters

Name Type Description
  • callback - An async with a result context containing success information. The returned task will complete in an arbitrary thread.

Returns

Type Description
void An async with a result context containing success information. The returned task will complete in an arbitrary thread.

Properties

Client

Retrieves the associated owner RemoteRenderingClient

auto GetClient() const noexcept -> ApiHandle<Microsoft::Azure::RemoteRendering::RemoteRenderingClient>;

ConnectionStatus

Current connection status of this session.

auto GetConnectionStatus() const noexcept -> Microsoft::Azure::RemoteRendering::ConnectionStatus;

See also

IsConnected

Utility function to query whether this session is connected.

auto GetIsConnected() const noexcept -> bool;

RendererInitOptions

Last connection parameters used in a call to RenderingSession.ConnectAsync(RendererInitOptions).

auto GetRendererInitOptions() const noexcept -> Microsoft::Azure::RemoteRendering::RendererInitOptions;

SessionUuid

String UUID of this session.

This can be used to connect to the session later or perform independent REST calls, for example with PowerShell.

auto GetSessionUuid(std::string & out) const noexcept -> void;

Valid

Whether this object is still valid.

An object is invalid if it has been destroyed or if the connection has been lost. It is an error to call any other function on an invalid object.

auto GetValid() const noexcept -> bool;

Events

ConnectionStatusChanged

Callback for connection status changes.

auto ConnectionStatusChanged(ConnectionStatusChangedEventHandler const& handler) noexcept -> Expected<event_token, Microsoft::Azure::RemoteRendering::Status>;
auto ConnectionStatusChanged(event_token& token) noexcept -> Microsoft::Azure::RemoteRendering::Status;

See also