Skip to content

Commit 8efe117

Browse files
alvinashcraftalvinashcraft
committed
Merged PR 22214: Add TransferTarget API ref docs for 11B SDK
Add TransferTarget API ref docs for 11B SDK. This is probably going to need some more work, but I wanted to get some eyes on it to make sure everything is technically correct before doing re-writes and removing some of the code snippets that are too simplistic. ---- #### AI description (iteration 1) #### PR Classification This pull request adds comprehensive API reference documentation for the TransferTarget API in the 11B SDK. #### PR Summary The pull request introduces a full set of new markdown documentation files that detail the TransferTarget API, including its classes, methods, properties, and events with usage examples and code samples. - `transfertargetwatcher.md`, along with its related event and method docs (e.g., TransferToAsync, IsSupported, Start, Stop, Added, Removed, Updated, EnumerationCompleted, Stopped), provides complete guidance on target discovery and monitoring. - `transfertarget.md`, `transfertargetinvokeresult.md`, and associated property files (e.g., Id, Label, DisplayIcon, IsEnabled, Succeeded, ExtendedError) document the core TransferTarget functionalities and result handling. - `transfertargetdiscoveryoptions.md` and its property-specific files (e.g., AllowedTargetAppIds, MaxAppTargets, DataPackage) explain the configuration options for discovering transfer targets. - Additional files (e.g., TransferTargetChangedEventArgs) offer detailed examples and event argument descriptions to aid developers in integrating these APIs. <!-- GitOpsUserAgent=GitOps.Apps.Server.pullrequestcopilot -->
2 parents b6a4b18 + dd821a1 commit 8efe117

26 files changed

Lines changed: 1279 additions & 0 deletions

‎windows.applicationmodel.datatransfer/transfertarget.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
-api-id: T:Windows.ApplicationModel.DataTransfer.TransferTarget
3+
-api-type: winrt class
4+
---
5+
6+
# Windows.ApplicationModel.DataTransfer.TransferTarget
7+
8+
<!--
9+
public sealed class TransferTarget
10+
-->
11+
12+
## -description
13+
14+
The `TransferTarget` class represents an application target for sharing data. It provides properties and methods to interact with and invoke the target for data transfer operations.
15+
16+
## -remarks
17+
18+
The `TransferTarget` class is part of the Transfer Target Platform API, which is designed to streamline the process of discovering and invoking transfer targets asynchronously. This API supports multiple providers and includes comprehensive filter options to ensure relevant targets are discovered efficiently.
19+
20+
#### Key Features
21+
22+
- **Asynchronous Target Discovery**: Ensures a responsive user experience by discovering targets asynchronously.
23+
- **Invocation Support**: Allows invoking transfer targets with a data package for seamless sharing.
24+
- **Real-Time Updates**: Provides events to notify applications about changes in available transfer targets.
25+
26+
## -see-also
27+
28+
[TransferTargetWatcher](transfertargetwatcher.md), [TransferTargetDiscoveryOptions](transfertargetdiscoveryoptions.md), [TransferTargetInvokeResult](transfertargetinvokeresult.md)
29+
30+
## -examples
31+
32+
#### Example - Discovering and Invoking a Transfer Target
33+
34+
```csharp
35+
var watcher = TransferTarget.CreateWatcher();
36+
TransferTarget discoveredTarget = null;
37+
38+
watcher.Added += (sender, args) =>
39+
{
40+
Console.WriteLine($"Target added: {args.Target.Label}");
41+
discoveredTarget = args.Target;
42+
};
43+
watcher.Start();
44+
45+
// Invoke a target with the parent window handle
46+
if (discoveredTarget != null)
47+
{
48+
var parentWindowId = Windows.UI.WindowId.CreateFromWindowHandle(hwnd);
49+
var result = await discoveredTarget.TransferToAsync(discoveredTarget, parentWindowId);
50+
}
51+
```

‎windows.applicationmodel.datatransfer/transfertarget_createwatcher_704384543.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
-api-id: M:Windows.ApplicationModel.DataTransfer.TransferTarget.CreateWatcher(Windows.ApplicationModel.DataTransfer.TransferTargetDiscoveryOptions)
3+
-api-type: winrt method
4+
---
5+
6+
# Windows.ApplicationModel.DataTransfer.TransferTarget.CreateWatcher(Windows.ApplicationModel.DataTransfer.TransferTargetDiscoveryOptions)
7+
8+
<!--
9+
public static Windows.ApplicationModel.DataTransfer.TransferTargetWatcher CreateWatcher (Windows.ApplicationModel.DataTransfer.TransferTargetDiscoveryOptions options);
10+
-->
11+
12+
13+
## -description
14+
15+
The `CreateWatcher` method creates a new instance of the `TransferTargetWatcher` class, configured with the specified discovery options. This method allows applications to customize the discovery process for transfer targets.
16+
17+
## -parameters
18+
19+
### -param options
20+
21+
The `TransferTargetDiscoveryOptions` used to configure the watcher. These options specify criteria such as allowed target app IDs and the maximum number of targets to discover.
22+
23+
## -returns
24+
25+
A `TransferTargetWatcher` instance configured with the provided discovery options.
26+
27+
## -remarks
28+
29+
The `CreateWatcher` method is a static method that initializes a `TransferTargetWatcher` with the specified options. Applications can use this method to tailor the discovery process to their specific needs.
30+
31+
#### Usage Notes:
32+
33+
- Ensure that the `options` parameter is properly configured before calling this method.
34+
- The returned watcher must be started using the `Start` method to begin discovery.
35+
36+
## -see-also
37+
38+
[TransferTargetWatcher](transfertargetwatcher.md), [TransferTargetDiscoveryOptions](transfertargetdiscoveryoptions.md)
39+
40+
## -examples
41+
42+
#### Example: Creating and Starting a TransferTargetWatcher
43+
44+
```csharp
45+
var options = new TransferTargetDiscoveryOptions
46+
{
47+
AllowedTargetAppIds = new List<string> { "App1", "App2" },
48+
MaxAppTargets = 5
49+
};
50+
51+
var watcher = TransferTarget.CreateWatcher(options);
52+
watcher.Start();
53+
```

‎windows.applicationmodel.datatransfer/transfertarget_displayicon.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
-api-id: P:Windows.ApplicationModel.DataTransfer.TransferTarget.DisplayIcon
3+
-api-type: winrt property
4+
---
5+
6+
# Windows.ApplicationModel.DataTransfer.TransferTarget.DisplayIcon
7+
8+
<!--
9+
public Windows.Storage.Streams.IRandomAccessStreamReference DisplayIcon { get; }
10+
-->
11+
12+
13+
## -description
14+
15+
The `DisplayIcon` property gets the icon associated with the transfer target. This icon is typically used to visually represent the target in the user interface.
16+
17+
## -property-value
18+
19+
A `IRandomAccessStreamReference` that represents the icon of the transfer target.
20+
21+
## -remarks
22+
23+
The `DisplayIcon` property provides a way to retrieve the visual representation of a transfer target. Applications can use this property to display the icon in their user interface, making it easier for users to identify the target.
24+
25+
#### Usage Notes:
26+
27+
- The icon can be displayed in lists or dialogs where transfer targets are presented to the user.
28+
- Ensure that the application handles cases where the icon might not be available.
29+
30+
## -see-also
31+
32+
[TransferTarget](transfertarget.md), [IRandomAccessStreamReference](https://learn.microsoft.com/uwp/api/windows.storage.streams.irandomaccessstreamreference)
33+
34+
## -examples
35+
36+
#### Example: Displaying the Icon of a Transfer Target
37+
38+
```csharp
39+
var icon = transferTarget.DisplayIcon;
40+
if (icon != null)
41+
{
42+
// Use the icon in the UI
43+
var bitmapImage = new BitmapImage();
44+
bitmapImage.SetSource(await icon.OpenReadAsync());
45+
myImageControl.Source = bitmapImage;
46+
}
47+
else
48+
{
49+
// Handle the case where no icon is available
50+
myImageControl.Source = null;
51+
}
52+
```

‎windows.applicationmodel.datatransfer/transfertarget_id.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
-api-id: P:Windows.ApplicationModel.DataTransfer.TransferTarget.Id
3+
-api-type: winrt property
4+
---
5+
6+
# Windows.ApplicationModel.DataTransfer.TransferTarget.Id
7+
8+
<!--
9+
public string Id { get; }
10+
-->
11+
12+
13+
## -description
14+
15+
The `Id` property gets the unique identifier of the transfer target. This identifier can be used to distinguish the target from others.
16+
17+
## -property-value
18+
19+
A `string` that represents the unique identifier of the transfer target.
20+
21+
## -remarks
22+
23+
The `Id` property provides a way to uniquely identify a transfer target. This is particularly useful in scenarios where multiple targets are available, and the application needs to track or reference a specific target.
24+
25+
#### Usage Notes:
26+
27+
- The `Id` is guaranteed to be unique for each transfer target in a given session.
28+
- Applications can use this property to store or compare transfer targets.
29+
30+
## -see-also
31+
32+
[TransferTarget](transfertarget.md)
33+
34+
## -examples
35+
36+
#### Example: Retrieving the ID of a Transfer Target
37+
38+
```csharp
39+
var targetId = transferTarget.Id;
40+
System.Diagnostics.Debug.WriteLine($"Transfer Target ID: {targetId}");
41+
```

‎windows.applicationmodel.datatransfer/transfertarget_isenabled.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
-api-id: P:Windows.ApplicationModel.DataTransfer.TransferTarget.IsEnabled
3+
-api-type: winrt property
4+
---
5+
6+
# Windows.ApplicationModel.DataTransfer.TransferTarget.IsEnabled
7+
8+
<!--
9+
public bool IsEnabled { get; }
10+
-->
11+
12+
13+
## -description
14+
15+
The `IsEnabled` property indicates whether the transfer target is currently enabled and available for use.
16+
17+
## -property-value
18+
19+
A `bool` value that is `true` if the transfer target is enabled; otherwise, `false`.
20+
21+
## -remarks
22+
23+
The `IsEnabled` property allows applications to determine whether a transfer target can be used for sharing operations. This is useful for filtering out targets that are temporarily unavailable.
24+
25+
#### Usage Notes:
26+
27+
- Check the `IsEnabled` property before attempting to invoke a transfer target.
28+
- An `IsEnabled` value of `false` may indicate that the target is disabled or not ready to accept data.
29+
30+
## -see-also
31+
32+
[TransferTarget](transfertarget.md)
33+
34+
## -examples
35+
36+
#### Example: Checking if a Transfer Target is Enabled
37+
38+
```csharp
39+
if (transferTarget.IsEnabled)
40+
{
41+
Console.WriteLine("The transfer target is enabled.");
42+
}
43+
else
44+
{
45+
Console.WriteLine("The transfer target is not enabled.");
46+
}
47+
```

‎windows.applicationmodel.datatransfer/transfertarget_label.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
-api-id: P:Windows.ApplicationModel.DataTransfer.TransferTarget.Label
3+
-api-type: winrt property
4+
---
5+
6+
# Windows.ApplicationModel.DataTransfer.TransferTarget.Label
7+
8+
<!--
9+
public string Label { get; }
10+
-->
11+
12+
13+
## -description
14+
15+
The `Label` property gets the display name of the transfer target. You typically show this name to users so they can identify the target.
16+
17+
## -property-value
18+
19+
A `string` that represents the display name of the transfer target.
20+
21+
## -remarks
22+
23+
The `Label` property provides a user-friendly name for the transfer target. It's localized based on the current user's locale selection.
24+
25+
Applications can use this property to display the name in their user interface, making it easier for users to select the desired target.
26+
27+
#### Usage Notes:
28+
29+
- The `Label` is intended for display purposes and might not be unique.
30+
- Combine the `Label` with other properties, such as `Id`, for unique identification if needed.
31+
32+
## -see-also
33+
34+
[TransferTarget](transfertarget.md)
35+
36+
## -examples
37+
38+
#### Example: Displaying the label of a transfer target
39+
40+
```csharp
41+
var targetLabel = transferTarget.Label;
42+
Console.WriteLine($"Transfer Target Label: {targetLabel}");
43+
```

‎windows.applicationmodel.datatransfer/transfertargetchangedeventargs.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
-api-id: T:Windows.ApplicationModel.DataTransfer.TransferTargetChangedEventArgs
3+
-api-type: winrt class
4+
---
5+
6+
# Windows.ApplicationModel.DataTransfer.TransferTargetChangedEventArgs
7+
8+
<!--
9+
public sealed class TransferTargetChangedEventArgs
10+
-->
11+
12+
13+
## -description
14+
15+
The `TransferTargetChangedEventArgs` class provides data for events that notify applications about changes to a transfer target, such as when a target is added, removed, or updated.
16+
17+
## -remarks
18+
19+
This class is used in conjunction with the `TransferTargetWatcher` to deliver detailed information about transfer target changes. It allows applications to respond dynamically to updates in the available transfer targets.
20+
21+
#### Key Properties:
22+
23+
- `Target`: Gets the transfer target associated with the event.
24+
25+
#### Usage:
26+
27+
This class is typically used in event handlers for the `Added`, `Removed`, and `Updated` events of the `TransferTargetWatcher`.
28+
29+
## -see-also
30+
31+
[TransferTargetWatcher](transfertargetwatcher.md), [TransferTarget](transfertarget.md)
32+
33+
## -examples
34+
35+
#### Example: Handling TransferTargetWatcher Events
36+
37+
```csharp
38+
watcher.Added += (sender, args) =>
39+
{
40+
Console.WriteLine($"New target added: {args.Target.Label}");
41+
};
42+
43+
watcher.Updated += (sender, args) =>
44+
{
45+
Console.WriteLine($"Target updated: {args.Target.Label}");
46+
};
47+
48+
watcher.Removed += (sender, args) =>
49+
{
50+
Console.WriteLine($"Target removed: {args.Target.Label}");
51+
};
52+
```
53+
54+

‎windows.applicationmodel.datatransfer/transfertargetchangedeventargs_target.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
-api-id: P:Windows.ApplicationModel.DataTransfer.TransferTargetChangedEventArgs.Target
3+
-api-type: winrt property
4+
---
5+
6+
# Windows.ApplicationModel.DataTransfer.TransferTargetChangedEventArgs.Target
7+
8+
<!--
9+
public Windows.ApplicationModel.DataTransfer.TransferTarget Target { get; }
10+
-->
11+
12+
13+
## -description
14+
15+
The `Target` property gets the transfer target associated with the event. This property provides details about the target that was added, removed, or updated.
16+
17+
## -property-value
18+
19+
A `TransferTarget` object that represents the transfer target associated with the event.
20+
21+
## -remarks
22+
23+
The `Target` property is used in event handlers for `TransferTargetWatcher` events such as `Added`, `Removed`, and `Updated`. It provides access to the transfer target that triggered the event.
24+
25+
#### Usage Notes:
26+
27+
- Use the `Target` property to retrieve details about the transfer target involved in the event.
28+
- The `Target` object contains additional properties such as `Id`, `Label`, and `IsEnabled`.
29+
30+
## -see-also
31+
32+
[TransferTargetWatcher](transfertargetwatcher.md), [TransferTarget](transfertarget.md)
33+
34+
## -examples
35+
36+
#### Example: Accessing the Target in an Event Handler
37+
38+
```csharp
39+
watcher.Added += (sender, args) =>
40+
{
41+
var target = args.Target;
42+
Console.WriteLine($"New target added: {target.Label}");
43+
};
44+
```
45+
46+

0 commit comments

Comments
 (0)