diff --git a/docs/api/ref/Metadata.md b/docs/api/ref/Metadata.md index a38413fb0..62d7c039a 100644 --- a/docs/api/ref/Metadata.md +++ b/docs/api/ref/Metadata.md @@ -9,7 +9,7 @@ FDC3 API operations return various types of metadata. ## `AppIntent` - + ```ts @@ -28,7 +28,19 @@ interface AppIntent { ```csharp -TBC +interface IAppIntent +{ + /// + /// Details of the intent whose relationship to resolving application is + /// being described. + /// + IIntentMetadata Intent { get; } + + /// + /// Details of applications that can resolve the intent. + /// + IEnumerable Apps { get; } +} ``` @@ -46,7 +58,7 @@ For each intent, it reference the applications that support that intent. ## `AppMetadata` - + ```ts @@ -104,7 +116,49 @@ interface AppMetadata extends AppIdentifier { ```csharp -TBC +interface IAppMetadata : IAppIdentifier +{ + /// + /// The unique app name that can be used with the open and raiseIntent calls. + /// + string? Name { get; } + + /// + /// The Version of the application. + /// + string? Version { get; } + + /// + /// A more user-friendly application title that can be used to render UI elements. + /// + string? Title { get; } + + /// + /// A tooltip for the application that can be used to render UI elements. + /// + string? Tooltip { get; } + + /// + /// A longer, multi-paragraph description for the application that could include markup. + /// + string? Description { get; } + + /// + /// A list of icon URLs for the application that can be used to render UI elements. + /// + IEnumerable Icons { get; } + + /// + /// A list of image URLs for the application that can be used to render UI elements. + /// + IEnumerable Screenshots { get; } + + /// + /// The type of output returned for any intent specified during resolution. May express a particular context type, + /// channel, or channel with specified type + /// + string? ResultType { get; } +} ``` @@ -128,7 +182,7 @@ Note that as `AppMetadata` instances are also `AppIdentifiers` they may be passe ## `ContextMetadata` - + ```ts @@ -144,7 +198,13 @@ interface ContextMetadata { ```csharp -TBC +interface IContextMetadata +{ + /// + /// Identifier for the app instance that sent the context and/or intent. + /// + IAppIdentifier? Source { get; } +} ``` @@ -165,7 +225,7 @@ Metadata relating to a context or intent & context received through the `addCont ## `DisplayMetadata` - + ```ts @@ -190,7 +250,24 @@ interface DisplayMetadata { ```csharp -TBC +interface IDisplayMetadata +{ + /// + /// A user-readable name for this channel, e.g: Red. + /// + string? Name { get; } + + /// + /// The color that should be associated within this channel when displaying this + /// channein in a UI, e.g: '0xFF0000'. + /// + string? Color { get; } + + /// + /// A URL of an image that can be used to display this channel. + /// + string? Glyph { get; } +} ``` @@ -205,7 +282,7 @@ A desktop agent (typically for _system_ channels) may want to provide additional ## `Icon` - + ```ts @@ -220,7 +297,23 @@ interface Icon { ```csharp -TBC +interface IIcon +{ + /// + /// The icon url + /// + string Src { get; } + + /// + /// The icon dimensions, formatted as '{height}x{width}' + /// + string? Size { get; } + + /// + /// Icon media type. If not present, the Desktop Agent may use the src file extension. + /// + string? Type { get; } +} ``` @@ -232,7 +325,7 @@ AppMetadata includes an icons property allowing multiple icon types to be specif **Example:** - + ```ts @@ -254,7 +347,7 @@ AppMetadata includes an icons property allowing multiple icon types to be specif ```csharp -TBC +IIcon? icon = appMetadata?.Icons.Where(icon => icon.Size == "48x48").First(); ``` @@ -272,7 +365,7 @@ TBC ## `Image` - + ```ts @@ -288,7 +381,29 @@ interface Image { ```csharp -TBC +interface IImage +{ + /// + /// The icon url + /// + string Src { get; } + + /// + /// The icon dimensions, formatted as '{height}x{width}' + /// + string? Size { get; } + + /// + /// Icon media type. If not present, the Desktop Agent may use the src file extension. + /// + string? Type { get; } + + + /// + /// Caption for the image + /// + string? Label { get; } +} ``` @@ -300,7 +415,7 @@ AppMetadata includes a screenshots property allowing multiple images to be speci **Example:** - + ```ts @@ -324,7 +439,10 @@ AppMetadata includes a screenshots property allowing multiple images to be speci ```csharp -TBC +foreach (IImage image in appMetadata.Screenshots) +{ + System.Diagnostics.Debug.WriteLine(image.Src); +} ``` @@ -342,7 +460,7 @@ TBC ## `ImplementationMetadata` - + ```ts @@ -389,7 +507,49 @@ interface ImplementationMetadata { ```csharp -TBC +interface IImplementationMetadata +{ + /// + /// The version number of the FDC3 specification that the implementation provides. + /// The string must be a numeric semver version, e.g. 1.2 or 1.2.1. + /// + string Fdc3Version { get; } + + /// + /// The name of the provider of the FDC3 Desktop Agent Implementation (e.g. Finsemble, Glue42, OpenFin etc.). + /// + string Provider { get; } + + /// + /// The version of the provider of the FDC3 Desktop Agent Implementation (e.g. 5.3.0). + /// + string ProviderVersion { get; } + + /// + /// Metadata indicating whether the Desktop Agent implements optional features of the Desktop Agent API. + /// + OptionalDesktopAgentFeatures OptionalFeatures { get; } + + /// + /// The calling application instance's own metadata according to the Desktop Agent + /// + IAppMetadata AppMetadata { get; } +} + +class OptionalDesktopAgentFeatures +{ + /// + /// Used to indicate whether the exposure of 'originating app metadata' for context and intent + /// messages is supported by the Desktop Agent. + /// + public bool OriginatingAppMetadata { get; set; } + + /// + /// Used to indicate whether the optional 'JoinUserChannel', 'GetCurrentChannel', and 'LeaveCurrentChannel' + /// are implemented by the Desktop Agent. + /// + public bool UserChannelMembershipAPIs { get; set; } +} ``` @@ -404,7 +564,7 @@ Metadata relating to the FDC3 [DesktopAgent](DesktopAgent) object and its provid ## `IntentMetadata` - + ```ts @@ -424,7 +584,18 @@ interface IntentMetadata { ```csharp -TBC +interface IIntentMetadata +{ + /// + /// The unique name of the intent that can be invoked by the raiseIntent call. + /// + string Name { get; } + + /// + /// A friendly display name for the intent that should be used to render UI elements. + /// + string DisplayName { get; } +} ``` @@ -438,7 +609,7 @@ The interface used to describe an intent within the platform. ## `IntentResolution` - + ```ts @@ -481,7 +652,25 @@ interface IntentResolution { ```csharp -TBC +interface IIntentResolution +{ + /// + /// The application that resolved the intent. + /// + IAppIdentifier Source { get; } + + /// + /// The intent that was raised. + /// + string Intent { get; } + + /// + /// The version number of the Intents schema being used. + /// + string? Version { get; } + + Task GetResult(); +} ``` @@ -491,7 +680,7 @@ IntentResolution provides a standard format for data returned upon resolving an **Examples:** - + ```ts @@ -528,7 +717,36 @@ try { ```csharp -TBC +var resolution = await _desktopAgent.RaiseIntent("QuoteStream", new Instrument(new InstrumentID() { Ticker = "AAPL" })); +try +{ + var result = await resolution.GetResult(); + + //check that we got a result and that it's a channel + if (result is IChannel channel) + { + var listener = await channel.AddContextListener("price", (quote, metadata) => System.Diagnostics.Debug.WriteLine(quote)); + + //if it's a PrivateChannel + if (channel is IPrivateChannel privateChannel) + { + privateChannel.OnDisconnect(() => { + System.Diagnostics.Debug.WriteLine("Quote feed went down"); + }); + + // Sometime later... + listener.Unsubscribe(); + } + } + else + { + System.Diagnostics.Debug.WriteLine($" {resolution.Source} did not return a channel"); + } +} +catch (Exception ex) +{ + // Handle exception +} ```