remoting/proto/control.proto - chromium/src.git - Git at Google

 // Copyright 2012 The Chromium Authors
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 //
 // Protocol for control messages.

 syntax = "proto2";

 option optimize_for = LITE_RUNTIME;

 package remoting.protocol;

 import "coordinates.proto";
 import "layout_key_function.proto";

 // Set the host resolution to match the client. If screen_id is omitted, then
 // the message will be ignored unless there is only one host display.
 //
 // If none of the fields (apart from screen_id) are present, restore the host
 // resolution instead.
 message ClientResolution {
   // Width and height of the client in device pixels.
   optional int32 width_pixels = 1;
   optional int32 height_pixels = 2;

   // Deprecated width and height of the client in device pixels.
   optional int32 width_deprecated = 3;
   optional int32 height_deprecated = 4;

   // Horizontal and vertical DPI of the screen. If either of these is zero or
   // unset, the corresponding DPI should be assumed to be 96 (Windows' default)
   // TODO(yuweih): Deprecate `y_dpi` and rename `x_dpi` to just `dpi`.
   optional int32 x_dpi = 5;
   optional int32 y_dpi = 6;

   // The screen_id from the most recent VideoTrackLayout message.
   optional int64 screen_id = 7;
 }

 message VideoControl {
   // Enables the video channel if true, pauses if false.
   optional bool enable = 1;

   message FramerateBoost {
     // Indicates whether to enable or disable this feature. When enabled, the
     // capture interval will be adjusted when remote input is received. The goal
     // is to reduce the latency between when input is received and a new frame
     // is generated which will lead to higher responsiveness when the user
     // interacts with the host.
     optional bool enabled = 1;

     // Adjusting the capture interval will change the framerate, a lower
     // interval value will typically lead to a higher FPS from the host.
     // The minimum value is 1, maximum is 1000 but that would lead to 1 FPS
     // which would be silly.
     optional int32 capture_interval_ms = 2;

     // Indicates the amount of time the capture interval will be boosted after
     // each remote input event is received.  Minimum value is 1, maximum is
     // 1000 (1 second).
     optional int32 boost_duration_ms = 3;
   }
   optional FramerateBoost framerate_boost = 4;

   // Sets the target framerate for the host. Note that the actual framerate is
   // variable so this value will update the rate at which frames are captured
   // but the framerate will be lower if there aren't enough changes on the
   // screen or the host is not capable of generating frames quickly enough.
   optional uint32 target_framerate = 5;

   // Lossless encode and color settings are no longer set via this message.
   reserved 2, 3;
   reserved "lossless_encode", "lossless_color";
 }

 message AudioControl {
   // Enables the audio channel if true, pauses if false.
   optional bool enable = 1;
 }

 message CursorShapeInfo {
   // Width, height (in screen pixels) of the cursor.
   optional int32 width = 1;
   optional int32 height = 2;

   // X,Y coordinates (relative to upper-left corner) of the cursor hotspot.
   optional int32 hotspot_x = 3;
   optional int32 hotspot_y = 4;

   // Cursor pixmap data in 32-bit BGRA format.
   optional bytes data = 5;

   // DPI of the cursor. This may be absent, which means the active display's DPI
   // will be used. It is recommended to set this field, since the cursor shape
   // may not come from the active display.
   optional int32 dpi = 6;
 }

 message Capabilities {
   // List of capabilities supported by the sender (case sensitive, capabilities
   // are separated by spaces).
   optional string capabilities = 1;
 }

 message PairingRequest {
   // Human-readable name of the client.
   optional string client_name = 1;
 }

 message PairingResponse {
   // Unique identifier for this client.
   optional string client_id = 1;

   // Shared secret for this client.
   optional string shared_secret = 2;
 }

 message ExtensionMessage {
   // The message type. This is used to dispatch the message to the correct
   // recipient.
   optional string type = 1;

   // String-encoded message data. The client and host must agree on the encoding
   // for each message type; different message types need not shared the same
   // encoding.
   optional string data = 2;
 }

 // This message describes the geometry and resolution of a single display.
 // For legacy video-layout messages, the geometry (x, y, width, height) is
 // specified in DIPs (device independent pixels). For extended video-layout
 // messages, the geometry is specified in "virtual screen" or "global
 // display" coordinates. See for example:
 // https://learn.microsoft.com/en-us/windows/win32/gdi/the-virtual-screen
 // https://developer.apple.com/documentation/coregraphics/1455788-cgeventgetlocation
 //
 // Each display may be mapped into this coordinate system according to its size
 // in pixels or in DIPs. If `pixel_type` is specified in the parent
 // `VideoLayout` message, then it will be used, otherwise it will be inferred
 // based on the host OS: on Windows and Linux/X11, displays are mapped in
 // pixels; on Mac and ChromeOS, displays are mapped in DIPs. All extended layout
 // messages are sent in global display coordinates.
 //
 // The same global display coordinates are used for injecting mouse events with
 // legacy (x, y) properties. But this fact is not important for newer hosts
 // which support fractional coordinates and ignore the legacy properties.
 message VideoTrackLayout {
   // Unique display identifier, from ScreenId in desktop_capture_types.h.
   // In client-to-host messages, an unset screen_id indicates that the client is
   // requesting a new display to be added to the display layout.
   optional int64 screen_id = 8;

   // Name of the video stream, from the WebRTC MediaStream.id property.
   // Absent in client-to-host messages if the client is requesting a new
   // display.
   optional string media_stream_id = 1;

   // Position of the top left corner of the rectangle covered by the video
   // track. See earlier comments for the units of measurement.
   optional int32 position_x = 2;
   optional int32 position_y = 3;

   // Size of the area covered by the video track. See earlier comments for
   // the units of measurement.
   optional int32 width = 4;
   optional int32 height = 5;

   // DPI of the screen.
   // TODO(yuweih): Deprecate `y_dpi` and rename `x_dpi` to just `dpi`.
   optional int32 x_dpi = 6;
   optional int32 y_dpi = 7;

   // Display name. This is displayed in the client UI and is informational only.
   optional string display_name = 9;

   // TODO(yuweih): Add bpp to the message.
 }

 message VideoLayout {
   enum PixelType {
     UNSPECIFIED_PIXEL_TYPE = 0;

     // Measurements are in physical screen pixels.
     PHYSICAL = 1;

     // Measurements are in logical pixels, aka. density-independent pixels
     // (DIPs).
     LOGICAL = 2;
   }

   // Layout for each video track.
   repeated VideoTrackLayout video_track = 1;

   // True if this display configuration supports capturing the entire desktop.
   // Absent in client-to-host messages.
   optional bool supports_full_desktop_capture = 2;

   // Screen ID of the display to be associated with the main window on the
   // client. If not set, the client will choose a sensible display to be
   // associated with the main window.
   //
   // This field is ignored in client-to-host messages.
   optional int64 primary_screen_id = 3;

   // The type of pixels used for the video layout. Logical pixels are preferred
   // because they preserve the density-independent display size on the client in
   // show-all-displays mode, and the client does not support mixed-DPI layouts
   // with physical pixels very well.
   // If unspecified, physical pixels are assumed if the host is Windows or
   // Linux, and logical pixels are assumed otherwise. The default behavior is
   // only for compatibility with older hosts, and new hosts should always
   // specify this field.
   optional PixelType pixel_type = 4;
 }

 message SelectDesktopDisplayRequest {
   // Identifier for display to select. Valid strings are "0", "1", ...
   // The "all" string is used to select the entire desktop.
   optional string id = 1;
 }

 // Next ID: 2
 message KeyboardLayout {
   // Next ID: 3
   message KeyAction {
     oneof action {
       LayoutKeyFunction function = 1;
       string character = 2;
     }
   }

   // Next ID: 2
   message KeyBehavior {
     // Maps 0-based shift level to key action. (Note: because this is zero-
     // based, it will be one less than the corresponding ISO shift level.)
     map<uint32, KeyAction> actions = 1;
   }

   // Map USB code to key behavior.
   map<uint32, KeyBehavior> keys = 1;
 }

 // Next ID: 2
 message TransportInfo {
   // Transport layer protocol the message sender uses to connect to the relay
   // server or the peer (if connection not relayed).
   // Possible values are those defined in the protocol and relayProtocol fields
   // in the RTCIceCandidateStats dictionary.
   // If the host failed to get protocol using WebRTC API, this field will be set
   // to "api-error".
   optional string protocol = 1;
 }

 // Next ID: 5
 message PeerConnectionParameters {
   // Sets preferred minimum and maximum bitrates. Unset fields means no
   // preference on the bitrate. Clients might need to keep track of existing
   // parameters if they need to do incremental changes.
   optional int32 preferred_min_bitrate_bps = 1;
   optional int32 preferred_max_bitrate_bps = 2;

   // Requests an ICE restart. This causes the host to initiate a new SDP
   // offer/answer exchange, and restarts the ICE gathering/connection sequence.
   // This can be used to re-establish a connection, without needing to
   // re-authenticate the user.
   optional bool request_ice_restart = 3;

   // Requests the host to initiate a new SDP offer/answer exchange, without
   // restarting ICE. This can be used to change SDP configuration (for example,
   // switching to a different codec), without needing a full reconnection.
   optional bool request_sdp_restart = 4;
 }

 // Next ID: 2
 message ActiveDisplay {
   optional int64 screen_id = 1;
 }

 // The position of the mouse cursor on the host. If the client receives a
 // HostCursorPosition with the fractional_coordinate, it should render the
 // host's cursor at the specified position. This may happen if relative mouse
 // mode is enabled, or a local mouse input is detected. If a client receives a
 // HostCursorPosition without the fractional_coordinate, it should hide the
 // host's cursor and revert to tracking the cursor position locally.
 // Next ID: 2
 message HostCursorPosition {
   optional FractionalCoordinate fractional_coordinate = 1;
 }
	// Copyright 2012 The Chromium Authors
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.
	//
	// Protocol for control messages.

	syntax = "proto2";

	option optimize_for = LITE_RUNTIME;

	package remoting.protocol;

	import "coordinates.proto";
	import "layout_key_function.proto";

	// Set the host resolution to match the client. If screen_id is omitted, then
	// the message will be ignored unless there is only one host display.
	//
	// If none of the fields (apart from screen_id) are present, restore the host
	// resolution instead.
	message ClientResolution {
	// Width and height of the client in device pixels.
	optional int32 width_pixels = 1;
	optional int32 height_pixels = 2;

	// Deprecated width and height of the client in device pixels.
	optional int32 width_deprecated = 3;
	optional int32 height_deprecated = 4;

	// Horizontal and vertical DPI of the screen. If either of these is zero or
	// unset, the corresponding DPI should be assumed to be 96 (Windows' default)
	// TODO(yuweih): Deprecate `y_dpi` and rename `x_dpi` to just `dpi`.
	optional int32 x_dpi = 5;
	optional int32 y_dpi = 6;

	// The screen_id from the most recent VideoTrackLayout message.
	optional int64 screen_id = 7;
	}

	message VideoControl {
	// Enables the video channel if true, pauses if false.
	optional bool enable = 1;

	message FramerateBoost {
	// Indicates whether to enable or disable this feature. When enabled, the
	// capture interval will be adjusted when remote input is received. The goal
	// is to reduce the latency between when input is received and a new frame
	// is generated which will lead to higher responsiveness when the user
	// interacts with the host.
	optional bool enabled = 1;

	// Adjusting the capture interval will change the framerate, a lower
	// interval value will typically lead to a higher FPS from the host.
	// The minimum value is 1, maximum is 1000 but that would lead to 1 FPS
	// which would be silly.
	optional int32 capture_interval_ms = 2;

	// Indicates the amount of time the capture interval will be boosted after
	// each remote input event is received. Minimum value is 1, maximum is
	// 1000 (1 second).
	optional int32 boost_duration_ms = 3;
	}
	optional FramerateBoost framerate_boost = 4;

	// Sets the target framerate for the host. Note that the actual framerate is
	// variable so this value will update the rate at which frames are captured
	// but the framerate will be lower if there aren't enough changes on the
	// screen or the host is not capable of generating frames quickly enough.
	optional uint32 target_framerate = 5;

	// Lossless encode and color settings are no longer set via this message.
	reserved 2, 3;
	reserved "lossless_encode", "lossless_color";
	}

	message AudioControl {
	// Enables the audio channel if true, pauses if false.
	optional bool enable = 1;
	}

	message CursorShapeInfo {
	// Width, height (in screen pixels) of the cursor.
	optional int32 width = 1;
	optional int32 height = 2;

	// X,Y coordinates (relative to upper-left corner) of the cursor hotspot.
	optional int32 hotspot_x = 3;
	optional int32 hotspot_y = 4;

	// Cursor pixmap data in 32-bit BGRA format.
	optional bytes data = 5;

	// DPI of the cursor. This may be absent, which means the active display's DPI
	// will be used. It is recommended to set this field, since the cursor shape
	// may not come from the active display.
	optional int32 dpi = 6;
	}

	message Capabilities {
	// List of capabilities supported by the sender (case sensitive, capabilities
	// are separated by spaces).
	optional string capabilities = 1;
	}

	message PairingRequest {
	// Human-readable name of the client.
	optional string client_name = 1;
	}

	message PairingResponse {
	// Unique identifier for this client.
	optional string client_id = 1;

	// Shared secret for this client.
	optional string shared_secret = 2;
	}

	message ExtensionMessage {
	// The message type. This is used to dispatch the message to the correct
	// recipient.
	optional string type = 1;

	// String-encoded message data. The client and host must agree on the encoding
	// for each message type; different message types need not shared the same
	// encoding.
	optional string data = 2;
	}

	// This message describes the geometry and resolution of a single display.
	// For legacy video-layout messages, the geometry (x, y, width, height) is
	// specified in DIPs (device independent pixels). For extended video-layout
	// messages, the geometry is specified in "virtual screen" or "global
	// display" coordinates. See for example:
	// https://learn.microsoft.com/en-us/windows/win32/gdi/the-virtual-screen
	// https://developer.apple.com/documentation/coregraphics/1455788-cgeventgetlocation
	//
	// Each display may be mapped into this coordinate system according to its size
	// in pixels or in DIPs. If `pixel_type` is specified in the parent
	// `VideoLayout` message, then it will be used, otherwise it will be inferred
	// based on the host OS: on Windows and Linux/X11, displays are mapped in
	// pixels; on Mac and ChromeOS, displays are mapped in DIPs. All extended layout
	// messages are sent in global display coordinates.
	//
	// The same global display coordinates are used for injecting mouse events with
	// legacy (x, y) properties. But this fact is not important for newer hosts
	// which support fractional coordinates and ignore the legacy properties.
	message VideoTrackLayout {
	// Unique display identifier, from ScreenId in desktop_capture_types.h.
	// In client-to-host messages, an unset screen_id indicates that the client is
	// requesting a new display to be added to the display layout.
	optional int64 screen_id = 8;

	// Name of the video stream, from the WebRTC MediaStream.id property.
	// Absent in client-to-host messages if the client is requesting a new
	// display.
	optional string media_stream_id = 1;

	// Position of the top left corner of the rectangle covered by the video
	// track. See earlier comments for the units of measurement.
	optional int32 position_x = 2;
	optional int32 position_y = 3;

	// Size of the area covered by the video track. See earlier comments for
	// the units of measurement.
	optional int32 width = 4;
	optional int32 height = 5;

	// DPI of the screen.
	// TODO(yuweih): Deprecate `y_dpi` and rename `x_dpi` to just `dpi`.
	optional int32 x_dpi = 6;
	optional int32 y_dpi = 7;

	// Display name. This is displayed in the client UI and is informational only.
	optional string display_name = 9;

	// TODO(yuweih): Add bpp to the message.
	}

	message VideoLayout {
	enum PixelType {
	UNSPECIFIED_PIXEL_TYPE = 0;

	// Measurements are in physical screen pixels.
	PHYSICAL = 1;

	// Measurements are in logical pixels, aka. density-independent pixels
	// (DIPs).
	LOGICAL = 2;
	}

	// Layout for each video track.
	repeated VideoTrackLayout video_track = 1;

	// True if this display configuration supports capturing the entire desktop.
	// Absent in client-to-host messages.
	optional bool supports_full_desktop_capture = 2;

	// Screen ID of the display to be associated with the main window on the
	// client. If not set, the client will choose a sensible display to be
	// associated with the main window.
	//
	// This field is ignored in client-to-host messages.
	optional int64 primary_screen_id = 3;

	// The type of pixels used for the video layout. Logical pixels are preferred
	// because they preserve the density-independent display size on the client in
	// show-all-displays mode, and the client does not support mixed-DPI layouts
	// with physical pixels very well.
	// If unspecified, physical pixels are assumed if the host is Windows or
	// Linux, and logical pixels are assumed otherwise. The default behavior is
	// only for compatibility with older hosts, and new hosts should always
	// specify this field.
	optional PixelType pixel_type = 4;
	}

	message SelectDesktopDisplayRequest {
	// Identifier for display to select. Valid strings are "0", "1", ...
	// The "all" string is used to select the entire desktop.
	optional string id = 1;
	}

	// Next ID: 2
	message KeyboardLayout {
	// Next ID: 3
	message KeyAction {
	oneof action {
	LayoutKeyFunction function = 1;
	string character = 2;
	}
	}

	// Next ID: 2
	message KeyBehavior {
	// Maps 0-based shift level to key action. (Note: because this is zero-
	// based, it will be one less than the corresponding ISO shift level.)
	map<uint32, KeyAction> actions = 1;
	}

	// Map USB code to key behavior.
	map<uint32, KeyBehavior> keys = 1;
	}

	// Next ID: 2
	message TransportInfo {
	// Transport layer protocol the message sender uses to connect to the relay
	// server or the peer (if connection not relayed).
	// Possible values are those defined in the protocol and relayProtocol fields
	// in the RTCIceCandidateStats dictionary.
	// If the host failed to get protocol using WebRTC API, this field will be set
	// to "api-error".
	optional string protocol = 1;
	}

	// Next ID: 5
	message PeerConnectionParameters {
	// Sets preferred minimum and maximum bitrates. Unset fields means no
	// preference on the bitrate. Clients might need to keep track of existing
	// parameters if they need to do incremental changes.
	optional int32 preferred_min_bitrate_bps = 1;
	optional int32 preferred_max_bitrate_bps = 2;

	// Requests an ICE restart. This causes the host to initiate a new SDP
	// offer/answer exchange, and restarts the ICE gathering/connection sequence.
	// This can be used to re-establish a connection, without needing to
	// re-authenticate the user.
	optional bool request_ice_restart = 3;

	// Requests the host to initiate a new SDP offer/answer exchange, without
	// restarting ICE. This can be used to change SDP configuration (for example,
	// switching to a different codec), without needing a full reconnection.
	optional bool request_sdp_restart = 4;
	}

	// Next ID: 2
	message ActiveDisplay {
	optional int64 screen_id = 1;
	}

	// The position of the mouse cursor on the host. If the client receives a
	// HostCursorPosition with the fractional_coordinate, it should render the
	// host's cursor at the specified position. This may happen if relative mouse
	// mode is enabled, or a local mouse input is detected. If a client receives a
	// HostCursorPosition without the fractional_coordinate, it should hide the
	// host's cursor and revert to tracking the cursor position locally.
	// Next ID: 2
	message HostCursorPosition {
	optional FractionalCoordinate fractional_coordinate = 1;
	}