Skip to content

Commit 44b7268

Browse files
bisoye-msftbisoye-msft
committed
Snipping tool protocol readme
1 parent 721c19a commit 44b7268

File tree

3 files changed

+199
-3
lines changed

3 files changed

+199
-3
lines changed

‎hub/apps/develop/launch/launch-screen-snipping.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,10 @@ ms.localizationpriority: medium
88
# customer-intent: As a Windows developer, I want to learn about the ms-screenclip and ms-screensketch URI schemes so that I can use them to launch the Snip & Sketch app or to open a new snip.
99
---
1010

11-
# Launch screen snipping
11+
# Launch screen snipping (Legacy)
12+
13+
**This is a legacy method for activating the Snipping Tool. It will be deprecated on 05/01/2025. Please refer to the updated documentation: [Launch Snipping Tool
14+
](/hub/apps/develop/launch/launch-snipping-tool.md)**
1215

1316
The **ms-screenclip:** and **ms-screensketch:** URI schemes allows you to initiate snipping or editing screenshots.
1417

‎hub/apps/develop/launch/launch-snipping-tool.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: Launch Snipping Tool
3+
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
6+
ms.topic: article
7+
keywords: windows 11, uri, snipping tool, capture
8+
ms.localizationpriority: medium
9+
ms.custom: RS5
10+
# 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+
---
12+
# Launch Snipping Tool
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.
15+
16+
Note: this protocol launch replaces the previous existing experience documented here:https://learn.microsoft.com/en-us/windows/uwp/launch-resume/launch-screen-snipping
17+
18+
## Supported Features include:
19+
* Rectangle Capture
20+
* Freeform Capture
21+
* Window Capture
22+
* Ability to launch directly into a Snip or Recording
23+
* Customizing features available
24+
* Autosave feature is available, but can be disabled
25+
26+
27+
## Protocol Specification
28+
29+
**URI Scheme:** {scheme}://{host}/{path}?{query}
30+
31+
**ms-screenclip:** takes the following parameters:
32+
33+
* **Scheme:** ms-screenclip - The custom scheme for the Snipping Tool protocol.
34+
* **Host:** Specifies the type of capture, e.g. capture, annotate.
35+
* **Path:** The media type being captured or annotated. /image, /video, /audio.
36+
* **Query:** Parameters for the specified schema
37+
38+
## Host (required)
39+
* Capture
40+
41+
## Path (required)
42+
* Image
43+
* Video
44+
45+
## EnabledModes Parameter
46+
47+
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.
48+
49+
Note: The FullScreenSnip mode is not supported in interactive mode at this time and should not be included in the enabledModes parameter.
50+
51+
52+
## Supported Modes
53+
54+
The **enabledModes** parameter can accept the following modes:
55+
56+
**RectangleSnip:** Enables rectangle capture mode.
57+
**WindowSnip:** Enables window capture mode.
58+
**FreeformSnip:** Enables freeform capture mode.
59+
**RectangleRecord:** Enables rectangle recording mode.
60+
**RecordAllModes:** Enables all recording modes (currently only RectangleRecord is available).
61+
**SnippingAllModes:** Enables all snipping (image capture) modes (RectangleSnip, WindowSnip, FreeformSnip).
62+
**All:** Enables all supported modes (RectangleSnip, WindowSnip, FreeformSnip, RectangleRecord).
63+
64+
**Important: If no enabledModes parameter is specified, the default behavior will allow all modes.**
65+
66+
## Examples
67+
68+
**Example 1: Enable Only Rectangle Snip **
69+
70+
ms-screenclip://capture/image?rectangle&enabledModes=RectangleSnip&redirect-uri=my-snip-protocol-test-app://response
71+
72+
73+
*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.*
74+
75+
**Example 2: Enable Rectangle Snip and Window Snip**
76+
77+
ms-screenclip://capture/image?rectangle&enabledModes=RectangleSnip,WindowSnip&redirect-uri=my-snip-protocol-test-app://response
78+
79+
80+
*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.*
81+
82+
**Example 3: Enable All Snipping Modes**
83+
84+
ms-screenclip://capture/image?rectangle&enabledModes=SnippingAllModes&redirect-uri=my-snip-protocol-test-app://response
85+
86+
87+
*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.*
88+
89+
**Example 4: Enable Recording Mode Only**
90+
91+
ms-screenclip://capture/video?enabledModes=RecordAllModes&redirect-uri=my-snip-protocol-test-app://response
92+
93+
94+
*Explanation: This command launches the Snipping Tool with only the recording mode enabled. The user can only choose the rectangle recording mode.*
95+
96+
**Example 5: Enable Multiple Snipping and Recording Modes**
97+
98+
ms-screenclip://capture/image?enabledModes=RectangleSnip,RectangleRecord&redirect-uri=my-snip-protocol-test-app://response
99+
100+
101+
*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.*
102+
103+
## Key Considerations
104+
105+
* **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.
106+
107+
* **Unsupported Modes:** The FullScreenSnip mode is not supported in interactive mode and should not be used in the enabledModes parameter.
108+
109+
* **Default Behavior:** If no enabledModes parameter is specified, all modes (RectangleSnip, WindowSnip, FreeformSnip, RectangleRecord) are available by default.
110+
111+
## Query
112+
113+
**ms-screenclip:**
114+
115+
| Parameter | Type | Required | Description | Default |
116+
|--------------------------|-----------------|----------|-----------------------------------------------------------------------------|-------------------|
117+
| api-version | string | "1.0" | Protocol version (e.g., "1.0"). This ensures compatibility and supports future enhancements. | "preview" |
118+
| user-agent | string | yes | Identifier for the calling application, used for logging and analytics. | n/a |
119+
| x-request-correlation-id | string | no | A unique identifier value attached to requests and messages that allow reference to a particular transaction or event chain. | Generated Guid if not provided. |
120+
| rectangle | (image & video) | no | Specifies the capture area as x,y,width,height. Leave Blank for interactive mode. | Interactive Mode |
121+
| Window | (Image) | no | Target window specified by hwnd. Leave Blank for interactive mode. | Interactive Mode |
122+
| Freeform | (Image) | no | Lets the user capture a freeform snip. | Interactive Mode |
123+
| FullScreen | (Image) | no | Captures the full screen snip. | Auto Mode |
124+
| redirect-uri | URI | yes | Callback URI protocol for the response. Applications must register a handler for this protocol. | n/a |
125+
126+
127+
## Parameter Validation
128+
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.
132+
133+
Response if expected parameters **aren't** supplied or overloaded
134+
135+
## Responses to the Caller
136+
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.
138+
139+
**Use of shared tokens**
140+
The use of the `SharedStorageAccessManager` class and of sharing tokens is subject to the following requirements and restrictions.
141+
142+
* A sharing token can only be redeemed one time. After that, the token is no longer valid.
143+
* A sharing token expires after 14 days and is no longer valid.
144+
*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+
## Response
147+
148+
| Parameter | Type | Description |
149+
|-------------------------|--------|------------------------------------------------------------------------------------------------------------------|
150+
| Reason | String | The outcome and explanation for the shipping outcomes. |
151+
| Token (for success) | String | A token representing the captured media, which the application can use to access the file. |
152+
| code | Int | The HTTP status code equivalent to provide a more granular understanding of the outcome. |
153+
| x-request-correlation-id| String | A unique identifier value attached to requests and messages that allow reference to a particular transaction or event chain. |
154+
155+
## Retrieving a token
156+
157+
I have developed a sample application to test the process of calling the protocol and converting the response token into media. Use the [SharedStorageAccessManager] (https://learn.microsoft.com/en-us/uwp/api/windows.applicationmodel.datatransfer.sharedstorageaccessmanager?view=winrt-26100)library to obtain the token.
158+
159+
[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)
160+
161+
## Status/code
162+
163+
| HTTP Status Code | Reason | Description |
164+
|------------------|------------------------------------------------|-----------------------------------------------------------------------------|
165+
| 200 | Success | The operation was successful. |
166+
| 400 | Bad Request - Invalid or Missing Parameters | The request cannot be processed due to client error. |
167+
| 408 | Request Timeout - Operation Took Too Long | The operation timed out before completion. |
168+
| 499 | Client Closed Request - User Cancelled the Snip| The user cancelled the snip, closing the request. |
169+
| 500 | Internal Server Error - Processing Failed | An error occurred on the server, preventing completion. |
170+
171+
172+
## Example Responses
173+
174+
| Use Case | Full URI Example |
175+
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
176+
| Successful Capture | my-snip-protocol-test-app://response/?code=200&reason=Success&request-correlation-id=CF99C5A5-3907-461E-A9A9-D8AAFFAD5031&token=8930-ASDFA-ASDF4545 |
177+
| Failed Capture | my-snip-protocol-test-app://response/?code=400&reason=Bad%20Request%20-%20Invalid%20value%20Missing%20Parameters&request-correlation-id=C7696B38-52C8-419A-880F-F3350D7A6626 |
178+
179+
180+
## Caller Example
181+
182+
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.
183+
184+
| Use Case | Example URI | Description |
185+
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
186+
| 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. |
187+
| 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.
188+
189+

‎hub/apps/toc.yml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -208,8 +208,12 @@ items:
208208
href: develop/launch/launch-store-app.md
209209
- name: Launch the Windows Maps app
210210
href: develop/launch/launch-maps-app.md
211-
- name: Launch screen snipping
212-
href: develop/launch/launch-screen-snipping.md
211+
- name: Launch Snipping Tool
212+
- items:
213+
- name: Launch Snipping Tool
214+
href: develop/launch/launch-snipping-tool.md
215+
- name: Launch screen snipping (legacy)
216+
href: develop/launch/launch-screen-snipping.md
213217
- name: Launch the People app
214218
href: develop/launch/launch-people-app.md
215219
- name: Support web-to-app linking with app URI handlers

0 commit comments

Comments
 (0)