You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: This topic describes how to use the new protocol launch framework for Snipping Tool. Your app can use these URI schemes to launch the Snipping Tool capture overlay to create a new snip or recording.
4
-
5
-
ms.date: 01/30/2025
4
+
ms.date: 02/14/2025
6
5
ms.topic: concept-article
7
6
keywords: windows 11, uri, snipping tool, capture
8
7
ms.localizationpriority: medium
9
8
ms.custom: RS5
10
9
# customer-intent: As a Windows developer, I want to learn about the ms-screenclip URI scheme so that I can integrate it into my application to programmatically launch the Snipping Tool. This will allow my application to trigger a snip experience directly, enabling users to take screenshots seamlessly without manually opening the Snipping Tool.
11
10
---
11
+
12
12
# Launch Snipping Tool
13
13
14
-
This article specifies the protocol for integrating first and third-party applications with the Windows Snipping Tool using the **ms-clip:** URI (Uniform Resource Identifier) scheme. The protocol facilitates the capture of images and video with audio via the Snipping Tool. App callers can customize and choose which Snipping Tool features their app will display. The protocol is designed to offer flexibility, security, and ease of use, aligning closely with familiar HTTP-based interactions. This shift can make the protocol more intuitive for developers and facilitate its integration with web technologies.
14
+
This article specifies the protocol for integrating first and third-party applications with the Windows Snipping Tool using the **ms-clip:** URI (Uniform Resource Identifier) scheme. The protocol facilitates the capture of images and video with audio via the Snipping Tool. App callers can customize and choose which Snipping Tool features their app will display. The protocol is designed to offer flexibility, security, and ease of use, aligning closely with familiar HTTP-based interactions. This shift can make the protocol more intuitive for developers and facilitate its integration with web technologies.
15
15
16
16
> [!NOTE]
17
17
> This protocol launch replaces the previous existing experience documented [here](launch-screen-snipping.md).
18
18
19
-
## Supported Features include:
19
+
## Supported features
20
20
21
-
* Rectangle Capture
22
-
* Freeform Capture
23
-
* Window Capture
24
-
* Ability to launch directly into a Snip or Recording
25
-
* Customizing features available
26
-
* Autosave feature is available, but can be disabled
21
+
The Snipping Tool protocol supports the following features:
27
22
23
+
- Rectangle Capture
24
+
- Freeform Capture
25
+
- Window Capture
26
+
- Ability to launch directly into a Snip or Recording
27
+
- Customizing features available
28
+
- Autosave feature is available, but can be disabled
28
29
29
30
## Protocol Specification
30
31
31
-
**URI Scheme:** {scheme}://{host}/{path}?{query}
32
+
**URI Scheme:**`{scheme}://{host}/{path}?{query}`
32
33
33
34
**ms-screenclip:** takes the following parameters:
34
35
35
-
***Scheme:** ms-screenclip - The custom scheme for the Snipping Tool protocol.
36
-
***Host:** Specifies the type of capture, e.g. capture, annotate.
37
-
***Path:** The media type being captured or annotated. /image, /video, /audio.
38
-
***Query:** Parameters for the specified schema
36
+
-**Scheme:**`ms-screenclip` - The custom scheme for the Snipping Tool protocol.
37
+
-**Host:** Specifies the type of capture, e.g. capture, annotate.
38
+
-**Path:** The media type being captured or annotated. /image, /video, /audio.
39
+
-**Query:** Parameters for the specified schema.
39
40
40
41
## Host (required)
41
-
* Capture
42
+
43
+
- Capture
42
44
43
45
## Path (required)
44
-
* Image
45
-
* Video
46
46
47
-
## EnabledModes Parameter
47
+
- Image
48
+
- Video
48
49
49
-
The enabledModes parameter is designed to give developers granular control over the available UI options when invoking the ms-screenclip protocol. This allows for a tailored user experience that matches the specific requirements of the calling application. By specifying the enabledModes parameter, developers can restrict the user's choices in the Snipping Tool UI to ensure the output format meets their expectations.
50
+
## EnabledModes parameter
50
51
51
-
> [!NOTE]
52
-
> The FullScreenSnip mode is not supported in interactive mode at this time and should not be included in the enabledModes parameter.
52
+
The enabledModes parameter is designed to give developers granular control over the available UI options when invoking the ms-screenclip protocol. This allows for a tailored user experience that matches the specific requirements of the calling application. By specifying the enabledModes parameter, developers can restrict the user's choices in the Snipping Tool UI to ensure the output format meets their expectations.
53
53
54
+
> [!NOTE]
55
+
> The FullScreenSnip mode is not supported in interactive mode at this time and should not be included in the enabledModes parameter.
54
56
55
-
## Supported Modes
57
+
## Supported modes
56
58
57
-
The **enabledModes** parameter can accept the following modes:
59
+
The **enabledModes** parameter can accept the following modes:
*Explanation: This command launches the Snipping Tool with only the rectangle snipping option enabled. The user will only be able to select a rectangular region for capture.*
78
+
*Explanation: This command launches the Snipping Tool with only the rectangle snipping option enabled. The user will only be able to select a rectangular region for capture.*
78
79
79
-
**Example 2: Enable Rectangle Snip and Window Snip**
80
+
### Example 2: Enable Rectangle Snip and Window Snip
*Explanation: This command launches the Snipping Tool with both the rectangle and window snipping modes enabled. The user can choose between capturing a rectangular area or an entire window.*
84
+
*Explanation: This command launches the Snipping Tool with both the rectangle and window snipping modes enabled. The user can choose between capturing a rectangular area or an entire window.*
*Explanation: This command launches the Snipping Tool with all supported image snipping modes (RectangleSnip, WindowSnip, FreeformSnip). The FullScreenSnip mode is excluded from interactive mode and will not be enabled.*
*Explanation: This command launches the Snipping Tool with both rectangle snip and rectangle recording modes available. Users can either snip a rectangle or record the selected area.*
106
103
107
-
## Key Considerations
108
-
109
-
***Mode Restrictions:** Developers should ensure that enabling specific modes aligns with the expected behavior of their application. Restricting UI options helps maintain a consistent user experience and ensures the resulting capture matches the application's needs.
104
+
## Key considerations
110
105
111
-
***Unsupported Modes:**The FullScreenSnip mode is not supported in interactive mode and should not be used in the enabledModes parameter.
112
-
113
-
***Default Behavior:** If no enabledModes parameter is specified, all modes (RectangleSnip, WindowSnip, FreeformSnip, RectangleRecord) are available by default.
106
+
-**Mode Restrictions:**Developers should ensure that enabling specific modes aligns with the expected behavior of their application. Restricting UI options helps maintain a consistent user experience and ensures the resulting capture matches the application's needs.
107
+
-**Unsupported Modes:** The FullScreenSnip mode is not supported in interactive mode and should not be used in the enabledModes parameter.
108
+
-**Default Behavior:** If no enabledModes parameter is specified, all modes (RectangleSnip, WindowSnip, FreeformSnip, RectangleRecord) are available by default.
| FullScreen | (Image) | no | Captures the full screen snip. | Auto Mode |
128
123
| redirect-uri | URI | yes | Callback URI protocol for the response. Applications must register a handler for this protocol. | n/a |
129
124
125
+
## Parameter validation
130
126
131
-
## Parameter Validation
127
+
The following validation checks should be performed on the parameters:
132
128
133
-
**Parameter Sanitization:** Validate and sanitize all input parameters to prevent injection attacks.
134
-
**Protocol Validation:** Ensure that the callback protocol string is validated against a list of allowed protocols to prevent injections or execution of malicious code.
135
-
**Required Fields:** Check that all required fields are provided and valid before proceeding with the snip operation.
129
+
-**Parameter Sanitization:** Validate and sanitize all input parameters to prevent injection attacks.
130
+
-**Protocol Validation:** Ensure that the callback protocol string is validated against a list of allowed protocols to prevent injections or execution of malicious code.
131
+
-**Required Fields:** Check that all required fields are provided and valid before proceeding with the snip operation.
136
132
137
-
Response if expected parameters **aren't** supplied or overloaded
133
+
Response if expected parameters **aren't** supplied or overloaded.
138
134
139
-
## Responses to the Caller
135
+
## Responses to the caller
140
136
141
137
To ensure the response back to the caller via `redirect-uri` follows HTTP-based interaction principles, the response will mimic the structure of an HTTP response but will be conveyed through URI query parameters. This approach keeps the interaction web-standard compliant and familiar to developers.
142
138
143
-
**Use of shared tokens**
144
-
The use of the `SharedStorageAccessManager` class and of sharing tokens is subject to the following requirements and restrictions.
139
+
### Use of shared tokens
140
+
141
+
The use of the `SharedStorageAccessManager` class and of sharing tokens is subject to the following requirements and restrictions:
142
+
143
+
- A sharing token can only be redeemed one time. After that, the token is no longer valid.
144
+
- A sharing token expires after 14 days and is no longer valid.
145
+
- The source app cannot provide more than one thousand sharing tokens. After a token is redeemed, removed, or expires, however, it no longer counts against the quota of the source app.
145
146
146
-
* A sharing token can only be redeemed one time. After that, the token is no longer valid.
147
-
* A sharing token expires after 14 days and is no longer valid.
148
-
*The source app cannot provide more than one thousand sharing tokens. After a token is redeemed, removed, or expires, however, it no longer counts against the quota of the source app.
147
+
### Response parameters
149
148
150
-
## Response
149
+
The following parameters are returned in the redirect URI:
@@ -158,11 +157,13 @@ The use of the `SharedStorageAccessManager` class and of sharing tokens is subje
158
157
159
158
## Retrieving a token
160
159
161
-
I have developed a sample application to test the process of calling the protocol and converting the response token into media. Use the [SharedStorageAccessManager](/uwp/api/windows.applicationmodel.datatransfer.sharedstorageaccessmanager) library to obtain the token.
160
+
A sample application is available to test the process of calling the protocol and converting the response token into media. Use the [SharedStorageAccessManager](/uwp/api/windows.applicationmodel.datatransfer.sharedstorageaccessmanager) library to obtain the token.
162
161
163
-
[Sample app code for retrieving tokens ](https://microsoft.visualstudio.com/Apps/_git/SnipProtocolTestApp?path=/SnipProtocolTestApp/MainPage.xaml.cs&version=GBmaster&line=139&lineEnd=140&lineStartColumn=1&lineEndColumn=1&lineStyle=plain&_a=contents)
162
+
The sample app code for retrieving tokens is available [here](https://microsoft.visualstudio.com/Apps/_git/SnipProtocolTestApp?path=/SnipProtocolTestApp/MainPage.xaml.cs&version=GBmaster&line=139&lineEnd=140&lineStartColumn=1&lineEndColumn=1&lineStyle=plain&_a=contents).
164
163
165
-
## Status/code
164
+
## Status codes
165
+
166
+
The following table lists the status codes that can be returned in the redirect URI:
Below is a table displaying examples of full URIs constructed to initiate different types of snipping sessions using the screenclip: protocol. Each URI example demonstrates a combination of parameters to illustrate how you can customize the snipping tool's behavior for different use cases.
185
+
Below is a table displaying examples of full URIs constructed to initiate different types of snipping sessions using the screenclip: protocol. Each URI example demonstrates a combination of parameters to illustrate how you can customize the snipping tool's behavior for different use cases.
| Rectangle Mode - Interactive | ms-screenclip://capture/image?user-agent=TestApp&Rectangle&uri=my-snip-protocol-test-app://response | An application initiates an interactive rectangle capture session, where the user selects the capture area. The result is redirected to a specific URI. |
191
-
| Video Mode - Interactive | ms-screenclip://capture/video?api-version=1.0&user-agent=TestApp&redirect-uri=my-snip-protocol-test-app://response | A video capture. Always in rectangle mode.
190
+
| Video Mode - Interactive | ms-screenclip://capture/video?api-version=1.0&user-agent=TestApp&redirect-uri=my-snip-protocol-test-app://response | A video capture. Always in rectangle mode. |
192
191
192
+
## Related content
193
193
194
+
-[Use Snipping Tool to capture screenshots](https://support.microsoft.com/windows/use-snipping-tool-to-capture-screenshots-00246869-1843-655f-f220-97299b865f6b)
0 commit comments