initial commit
This commit is contained in:
@@ -0,0 +1,359 @@
|
||||
using System.Windows;
|
||||
|
||||
namespace LiveWall.Sdk;
|
||||
|
||||
/// <summary>Version of the plugin API. Bumped when contracts change in an incompatible way.</summary>
|
||||
public static class PluginApi
|
||||
{
|
||||
/// <summary>Current contract version. Plugins must declare a compatible version in plugin.json.</summary>
|
||||
public const string Version = "1.0";
|
||||
|
||||
/// <summary>Host application version this SDK shipped with (informational).</summary>
|
||||
public const string HostVersion = "1.8.4";
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// What a plugin is allowed to do, declared in its <c>plugin.json</c> and shown to the user before
|
||||
/// the plugin is enabled. These are declarations, not a sandbox: a plugin runs inside LiveWall's
|
||||
/// process with full .NET rights. They exist so the user knows what they are agreeing to.
|
||||
/// </summary>
|
||||
[Flags]
|
||||
public enum PluginPermission
|
||||
{
|
||||
None = 0,
|
||||
|
||||
/// <summary>Read the current wallpaper, playback state and a snapshot of the settings.</summary>
|
||||
ReadWallpaper = 1 << 0,
|
||||
|
||||
/// <summary>Play / pause / next / set the wallpaper.</summary>
|
||||
ControlPlayback = 1 << 1,
|
||||
|
||||
/// <summary>Draw a layer on top of the wallpaper (clocks, visualisers, badges…).</summary>
|
||||
DesktopOverlay = 1 << 2,
|
||||
|
||||
/// <summary>Contribute pages to the LiveWall settings window.</summary>
|
||||
SettingsUi = 1 << 3,
|
||||
|
||||
/// <summary>Contribute commands the user can run from the app.</summary>
|
||||
Commands = 1 << 4,
|
||||
|
||||
/// <summary>Contribute entries to the tray menu.</summary>
|
||||
TrayMenu = 1 << 5,
|
||||
|
||||
/// <summary>Register global hotkeys.</summary>
|
||||
Hotkeys = 1 << 6,
|
||||
|
||||
/// <summary>Read and write files (the plugin's data folder, and anything the user points it at).</summary>
|
||||
FileSystem = 1 << 7,
|
||||
|
||||
/// <summary>Make outbound network requests.</summary>
|
||||
Network = 1 << 8,
|
||||
|
||||
/// <summary>Supply a wallpaper renderer for sources it claims (overrides the built-in players).</summary>
|
||||
Renderer = 1 << 9,
|
||||
|
||||
/// <summary>Rewrite or veto wallpaper requests before the engine applies them.</summary>
|
||||
Filters = 1 << 10,
|
||||
|
||||
All = ReadWallpaper | ControlPlayback | DesktopOverlay | SettingsUi | Commands | TrayMenu |
|
||||
Hotkeys | FileSystem | Network | Renderer | Filters
|
||||
}
|
||||
|
||||
/// <summary>Human readable description of what every permission means (used by the warning dialog).</summary>
|
||||
public static class PluginPermissionInfo
|
||||
{
|
||||
public static string Describe(PluginPermission permission) => permission switch
|
||||
{
|
||||
PluginPermission.ReadWallpaper => "Read your current wallpaper, playback state and settings",
|
||||
PluginPermission.ControlPlayback => "Start, stop, skip and replace your wallpaper",
|
||||
PluginPermission.DesktopOverlay => "Draw content on top of your desktop wallpaper",
|
||||
PluginPermission.SettingsUi => "Add pages to the LiveWall settings window",
|
||||
PluginPermission.Commands => "Add commands to LiveWall",
|
||||
PluginPermission.TrayMenu => "Add entries to the LiveWall tray menu",
|
||||
PluginPermission.Hotkeys => "Register system-wide keyboard shortcuts",
|
||||
PluginPermission.FileSystem => "Read and write files on your computer",
|
||||
PluginPermission.Network => "Connect to the internet",
|
||||
PluginPermission.Renderer => "Take over wallpaper playback with its own renderer",
|
||||
PluginPermission.Filters => "Rewrite or block wallpaper changes",
|
||||
_ => permission.ToString()
|
||||
};
|
||||
|
||||
/// <summary>Expands a flag set into individual descriptions.</summary>
|
||||
public static IReadOnlyList<(PluginPermission Permission, string Description)> Expand(PluginPermission permissions)
|
||||
{
|
||||
var list = new List<(PluginPermission, string)>();
|
||||
foreach (PluginPermission p in Enum.GetValues<PluginPermission>())
|
||||
{
|
||||
if (p is PluginPermission.None or PluginPermission.All) continue;
|
||||
if (permissions.HasFlag(p)) list.Add((p, Describe(p)));
|
||||
}
|
||||
return list;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Everything the host knows about a plugin. Filled in by LiveWall before Initialize.</summary>
|
||||
public sealed class PluginInfo
|
||||
{
|
||||
public string Id { get; init; } = "";
|
||||
public string Name { get; init; } = "";
|
||||
public string Version { get; init; } = "";
|
||||
public string Author { get; init; } = "";
|
||||
public string Description { get; init; } = "";
|
||||
public string Homepage { get; init; } = "";
|
||||
public string ApiVersion { get; init; } = "";
|
||||
public PluginPermission Permissions { get; init; }
|
||||
|
||||
/// <summary>Absolute path of the plugin folder.</summary>
|
||||
public string Folder { get; init; } = "";
|
||||
|
||||
/// <summary>Absolute path of the plugin assembly.</summary>
|
||||
public string AssemblyPath { get; init; } = "";
|
||||
|
||||
/// <summary>SHA-256 of the plugin assembly (lower case hex).</summary>
|
||||
public string Sha256 { get; init; } = "";
|
||||
|
||||
/// <summary>
|
||||
/// True when the loaded assembly hash matches the hash the user trusted on this machine, or the
|
||||
/// publisher ships it in LiveWall's built-in trusted list. Unverified plugins run with a warning.
|
||||
/// </summary>
|
||||
public bool Verified { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>The plugin entry point. One public class implementing this per assembly.</summary>
|
||||
public interface ILiveWallPlugin
|
||||
{
|
||||
/// <summary>
|
||||
/// Called once, on the UI thread, after the user enabled the plugin. Register your extensions
|
||||
/// and subscribe to events here. Exceptions are caught, logged and disable the plugin.
|
||||
/// </summary>
|
||||
void Initialize(IPluginContext context);
|
||||
|
||||
/// <summary>Called when the plugin is disabled, reloaded or the app is closing.</summary>
|
||||
void Shutdown();
|
||||
}
|
||||
|
||||
/// <summary>Everything a plugin can reach. One instance per plugin.</summary>
|
||||
public interface IPluginContext
|
||||
{
|
||||
PluginInfo Info { get; }
|
||||
|
||||
/// <summary>Writes to the LiveWall log next to the host's own messages.</summary>
|
||||
IPluginLog Log { get; }
|
||||
|
||||
/// <summary>Persistent key/value storage owned by the plugin (JSON file in its data folder).</summary>
|
||||
IPluginStorage Storage { get; }
|
||||
|
||||
/// <summary>Read-only snapshot of the user's configuration.</summary>
|
||||
ISettingsSnapshot Settings { get; }
|
||||
|
||||
/// <summary>Actions a plugin may trigger in the host.</summary>
|
||||
IHostActions Host { get; }
|
||||
|
||||
/// <summary>Type based publish/subscribe bus.</summary>
|
||||
IPluginEvents Events { get; }
|
||||
|
||||
/// <summary>Registers extension points (overlays, pages, commands, renderers, filters, hotkeys).</summary>
|
||||
IPluginRegistrar Extensions { get; }
|
||||
|
||||
/// <summary>Cancelled when the plugin is being shut down. Pass it to your async work.</summary>
|
||||
CancellationToken ShutdownToken { get; }
|
||||
}
|
||||
|
||||
/// <summary>Logging façade. Everything lands in %APPDATA%\LiveWall\logs.</summary>
|
||||
public interface IPluginLog
|
||||
{
|
||||
void Debug(string message);
|
||||
void Info(string message);
|
||||
void Warn(string message);
|
||||
void Error(string message, Exception? exception = null);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Per plugin JSON storage. Values are serialised with System.Text.Json, so any POCO works.
|
||||
/// </summary>
|
||||
public interface IPluginStorage
|
||||
{
|
||||
/// <summary>The plugin's private data folder (created on demand).</summary>
|
||||
string DataFolder { get; }
|
||||
|
||||
T? Get<T>(string key, T? fallback = default);
|
||||
void Set<T>(string key, T value);
|
||||
bool Remove(string key);
|
||||
IReadOnlyCollection<string> Keys { get; }
|
||||
|
||||
/// <summary>Absolute path inside the data folder; the directory is created for you.</summary>
|
||||
string PathFor(string fileName);
|
||||
|
||||
/// <summary>Writes pending changes immediately (normally done automatically).</summary>
|
||||
void Flush();
|
||||
}
|
||||
|
||||
/// <summary>Read-only view of the live settings.</summary>
|
||||
public interface ISettingsSnapshot
|
||||
{
|
||||
Guid SnapshotId { get; }
|
||||
string SourceKind { get; } // "Video", "AnimatedGif", "Image", "YouTube", "WebPage"
|
||||
string SourceLocation { get; } // file path or URL
|
||||
bool Muted { get; }
|
||||
double Volume { get; } // 0–100
|
||||
double Speed { get; } // 0.25–4
|
||||
bool Loop { get; }
|
||||
bool InteractiveMode { get; }
|
||||
bool Paused { get; }
|
||||
int DimPercent { get; }
|
||||
string DimColor { get; }
|
||||
IReadOnlyList<string> DisplayDevices { get; }
|
||||
}
|
||||
|
||||
/// <summary>The current wallpaper, as seen by plugins.</summary>
|
||||
public sealed class WallpaperState
|
||||
{
|
||||
public string Kind { get; init; } = "";
|
||||
public string Source { get; init; } = "";
|
||||
public string Title { get; init; } = "";
|
||||
public bool IsPlaying { get; init; }
|
||||
public bool IsPaused { get; init; }
|
||||
public bool IsInteractive { get; init; }
|
||||
public bool SuppliedByPlugin { get; init; }
|
||||
public string RendererName { get; init; } = "";
|
||||
}
|
||||
|
||||
/// <summary>Host actions. Each one is a no-op when the plugin lacks the permission for it.</summary>
|
||||
public interface IHostActions
|
||||
{
|
||||
WallpaperState Current { get; }
|
||||
|
||||
/// <summary>Replaces the wallpaper (needs <see cref="PluginPermission.ControlPlayback"/>).</summary>
|
||||
void SetWallpaper(WallpaperRequest request);
|
||||
|
||||
void Play();
|
||||
void Pause();
|
||||
void TogglePause();
|
||||
void NextWallpaper();
|
||||
void ReloadWallpaper();
|
||||
void Reattach();
|
||||
|
||||
/// <summary>Opens the LiveWall settings window.</summary>
|
||||
void OpenSettings();
|
||||
|
||||
/// <summary>Status line in the settings window.</summary>
|
||||
void SetStatus(string text);
|
||||
|
||||
/// <summary>Balloon notification (respects the user's notification setting).</summary>
|
||||
void ShowNotification(string title, string message);
|
||||
|
||||
/// <summary>Shows or hides the desktop overlay layer for this plugin.</summary>
|
||||
void SetOverlayVisible(bool visible);
|
||||
}
|
||||
|
||||
/// <summary>A wallpaper a plugin wants to show.</summary>
|
||||
public sealed class WallpaperRequest
|
||||
{
|
||||
/// <summary>"Video", "AnimatedGif", "Image", "YouTube", "WebPage" or "Custom".</summary>
|
||||
public string Kind { get; set; } = "Custom";
|
||||
|
||||
/// <summary>File path, URL or any string your renderer interprets.</summary>
|
||||
public string Source { get; set; } = "";
|
||||
|
||||
public string Title { get; set; } = "";
|
||||
|
||||
/// <summary>Free-form data for your own renderer (survives filters, not persisted).</summary>
|
||||
public Dictionary<string, string> Metadata { get; } = new(StringComparer.OrdinalIgnoreCase);
|
||||
|
||||
public WallpaperRequest Clone()
|
||||
{
|
||||
var clone = new WallpaperRequest { Kind = Kind, Source = Source, Title = Title };
|
||||
foreach (var pair in Metadata) clone.Metadata[pair.Key] = pair.Value;
|
||||
return clone;
|
||||
}
|
||||
|
||||
public override string ToString() => $"{Kind}:{Source}";
|
||||
}
|
||||
|
||||
/// <summary>Registers extension points. All calls are thread safe and may happen in Initialize.</summary>
|
||||
public interface IPluginRegistrar
|
||||
{
|
||||
/// <summary>Draws above the wallpaper (needs <see cref="PluginPermission.DesktopOverlay"/>).</summary>
|
||||
void AddOverlay(IWallpaperOverlay overlay);
|
||||
|
||||
void RemoveOverlay(IWallpaperOverlay overlay);
|
||||
|
||||
/// <summary>Adds a page to the Plugins tab (needs <see cref="PluginPermission.SettingsUi"/>).</summary>
|
||||
void AddSettingsPage(IPluginSettingsPage page);
|
||||
|
||||
/// <summary>Adds a command to the app and the tray menu.</summary>
|
||||
void AddCommand(PluginCommand command);
|
||||
|
||||
/// <summary>Adds a wallpaper filter (needs <see cref="PluginPermission.Filters"/>).</summary>
|
||||
void AddFilter(IWallpaperFilter filter);
|
||||
|
||||
/// <summary>Takes over rendering of sources it claims (needs <see cref="PluginPermission.Renderer"/>).</summary>
|
||||
void AddRenderer(IWallpaperRendererPlugin renderer);
|
||||
|
||||
/// <summary>Registers a global hotkey such as "Ctrl+Alt+K" (needs <see cref="PluginPermission.Hotkeys"/>).</summary>
|
||||
void AddHotkey(PluginHotkey hotkey);
|
||||
}
|
||||
|
||||
/// <summary>An entry in the app's plugin command list and the tray menu.</summary>
|
||||
public sealed class PluginCommand
|
||||
{
|
||||
public PluginCommand(string id, string title, Action<PluginCommandContext> execute)
|
||||
{
|
||||
Id = id;
|
||||
Title = title;
|
||||
Execute = execute;
|
||||
}
|
||||
|
||||
public string Id { get; }
|
||||
public string Title { get; set; }
|
||||
|
||||
/// <summary>Optional grouping label, e.g. "Wallpaper".</summary>
|
||||
public string Category { get; set; } = "";
|
||||
|
||||
/// <summary>Return false to disable the entry (evaluated when the menu opens).</summary>
|
||||
public Func<bool>? CanExecute { get; set; }
|
||||
|
||||
internal Action<PluginCommandContext> Execute { get; }
|
||||
|
||||
public void Run(PluginCommandContext context) => Execute(context);
|
||||
}
|
||||
|
||||
/// <summary>Passed to <see cref="PluginCommand"/>.</summary>
|
||||
public sealed class PluginCommandContext
|
||||
{
|
||||
public PluginCommandContext(IPluginContext plugin, IHostActions host)
|
||||
{
|
||||
Plugin = plugin;
|
||||
Host = host;
|
||||
}
|
||||
|
||||
public IPluginContext Plugin { get; }
|
||||
public IHostActions Host { get; }
|
||||
}
|
||||
|
||||
/// <summary>A global keyboard shortcut contributed by a plugin.</summary>
|
||||
public sealed class PluginHotkey
|
||||
{
|
||||
public PluginHotkey(string id, string gesture, Action action)
|
||||
{
|
||||
Id = id;
|
||||
Gesture = gesture;
|
||||
Action = action;
|
||||
}
|
||||
|
||||
public string Id { get; }
|
||||
|
||||
/// <summary>Combination such as "Ctrl+Alt+K", parsed like LiveWall's own hotkeys.</summary>
|
||||
public string Gesture { get; }
|
||||
|
||||
public string Description { get; set; } = "";
|
||||
|
||||
public Action Action { get; }
|
||||
}
|
||||
|
||||
/// <summary>Raised by plugins to inform others about something (or to listen).</summary>
|
||||
public interface IPluginEvents
|
||||
{
|
||||
IDisposable Subscribe<TEvent>(Action<TEvent> handler) where TEvent : class;
|
||||
void Publish<TEvent>(TEvent payload) where TEvent : class;
|
||||
}
|
||||
Reference in New Issue
Block a user