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.
- A Result.AlreadyConnected error occurs, if another session in the same process is already connected to its runtime.
- A Result.InProgress error occurs, if Connect has been called before.
- A Result.OtherSessionConnected error occurs, if another session is already connected to this runtime.
- A Result.NoConnection error occurs, if no connection could be established.
- 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 or RenderingSession 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.
- A Result.UnsupportedDisplayAdapter error occurs if an unsupported display adapter is detected.
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;