v1.1: Add lockscreen support, offline mode

Add Readme files and batch scripts
Add support for setting global lock screen
Add support for loading image from a file or directory
Fix wallpaper being set using a relative path

.gitignore

@@ -2,4 +2,5 @@
 Other
 SpotlightDownloader/bin
 SpotlightDownloader/obj
+SpotlightDownloader/*.user
 .vs

README-En.txt

@@ -0,0 +1,107 @@
+=====================================================
+==== SpotlightDL v1.1 - By ORelio - Microzoom.fr ====
+=====================================================
+
+Thanks for dowloading SpotlightDL!
+
+This program can retrieve Windows Spotlight images by requesting the Microsoft Spotlight API.
+SpotlightDL can also define images as wallpaper and system-wide lockscreen image.
+
+It is useful in the following use cases:
+ - Download the whole Spotlight library with maximum image resolution and metadata
+ - Define Spotlight images as wallpaper, not only on Windows 10 but also on previous versions
+ - Define Spotlight images as global lock screen: without ads, and without any user being logged in
+ - Chain SpotlightDL with your own scripts and apps by taking advantage of the url mode
+
+============
+ How to use
+============
+
+Extract the archive if not already extracted, then call SpotlightDownloader.exe from the command line.
+If you are not used to the command prompt, a few Batch files are offered for your convenience:
+
+spotlight-download
+  This script downloads as much images as possible from the Spotlight API,
+  with maximum res and metadata. Please note that there is no actual way
+  of listing *all* images so SpotlightDownloader will make many API calls
+  to discover and download new images, and stop when no new images are
+  discovered. It may miss a few images but you should get most of them.
+
+update-wallpaper
+  This script maintains a cache of several Spotlight pictures
+  and randomly defines a new Spotlight image as wallpaper
+  the cache allows a few updates without Internet access.
+
+update-lockscreen
+  Same as update-wallpaper but defines images as system-wide lockscreen
+  This script must be run as administrator as it replaces an image in the
+  Windows folder and clear the lockscreen cache to force a lockscreen refresh.
+
+restore-lockscreen
+  This script restores the default lock screen image from Windows 10
+  This script must be run as administrator.
+
+generate-manual
+  This script saves usage info as a text file for your convenience,
+  in order to help writing your own batch files or PowerShell scripts.
+
+hide-console
+  This script launches another script without showing the console window.
+  Mostly useful if you plan to schedule an update script on logon.
+  The path passed as argument should not contain special characters.
+
+===========================
+ Scheduling a batch script
+===========================
+
+If you wish to periodically update your wallpaper or lockscreen,
+you can schedule one of the provided script by following these instructions:
+
+= If you are not administrator =
+= Startup shortcut method =
+
+Use Win+R keyboard shortcut and specify:
+  %appdata%\Microsoft\Windows\Start Menu\Programs\Startup
+
+Perform a right click inside the Startup folder > New > Shortcut
+  wscript "C:\Path\To\hide-console.vbs" "C:\Path\To\desired-script.bat"
+  Next > Type a meaningful name for that shortcut > Finish
+
+The shortcut will launch on each logon and run the script.
+Note: lockscreen-related scripts won't work with this method.
+
+= If you are administrator =
+= Task scheduler method =
+
+Use Win+R and specify:
+  taskschd.msc
+
+Click "Create a new task"
+  General tab
+    - Define the task name
+    - Check "Run with highest privileges" to run the script as admin (lockscreen...)
+  Triggers tab
+    - Click New and add a trigger: "At log on" or "On a schedule" for instance
+  Actions tab
+    - Click New, choose Start a program
+    - Program/Script: wscript
+    - Add arguments: "C:\Path\To\hide-console.vbs" "C:\Path\To\desired-script.bat"
+  Conditions tab
+    - You may want to uncheck "Start the task only if the computer is on AC power"
+  Settings tab
+    - If your task has a defined schedule, e.g. everyday at 10am but your computer
+      is powered off at 10am, the task will not run. You may want to enable the
+      "Run task as soon as possible after a sheduled start is missed" feature.
+
+Click OK to save your task.
+
+=====
+ FAQ
+=====
+
+Q: The lockscreen does not appear when I am logged on?
+R: Make sure the image is also seleted in your personal lock screen settings.
+
++---------------+
+| © 2018 ORelio |
++---------------+

README-Fr.txt

@@ -0,0 +1,108 @@
+======================================================
+==== SpotlightDL v1.1 - Par ORelio - Microzoom.fr ====
+======================================================
+
+Merci d'avoir téléchargé SpotlightDL!
+
+Ce programme permet de récupérer les images de "Windows à la une" directement depuis l'API de Microsoft.
+SpotlightDL peut également définir des images en tant que fond d'écran ou sur l'écran de verouillage global.
+
+Ce programme est utile dans les cas suivants :
+ - Télécharger toute la bibliothèque d'images en définition maximale, avec fichiers de métadonnées
+ - Définir les images en tant que fond d'écran, non seulement sous Windows 10 mais aussi sur les versions précédentes
+ - Définir les images sur l'écran de verouillage global, sans les publicités, et même lorsqu'aucune session n'est ouverte
+ - Utiliser SpotlightDL dans vos propres scripts et programmes en appelant la fonction récupérant les URL des images
+
+=============
+ Utilisation
+=============
+
+Extraire l'archive si cela n'est pas déjà fait, puis appeler SpotlightDownloader.exe depuis l'invite de commande.
+Si vous n'avez pas l'habitude de l'invite de commande, quelques scripts Batch sont fournis pour vous aider :
+
+spotlight-download
+  Ce script télécharge autant d'images que possibles depuis l'API Windows à la une, en demandant
+  la définition maximale et en sauvegardant les métadonnées. N'étant pas possible de lister toutes
+  les images d'un coup, SpotlightDL va effectuer beaucoup d'appels à l'API pour découvrir autant
+  d'images que possible, puis s'arrêter lorsqu'aucune nouvelle image n'est découverte.
+  Vous pourriez manquer quelques images, mais devriez en obtenir la plupart.
+
+update-wallpaper
+  Ce script maintient un cache de quelques images et en définit une au hasard en tant que fond d'écran.
+  Le cache permet d'avoir un peu de changement au niveau du fond d'écran même lorsque vous n'avez pas Internet.
+
+update-lockscreen
+  Même fonctionnement qu'update-wallpaper mais définit l'image en tant qu'écran de verouillage global.
+  Ce script doit être lancé en tant qu'administrateur car il remplace une image dans le dossier Windows
+  et vide le cache de l'écran de verouillage afin d'en forcer la mise à jour immédiate.
+
+restore-lockscreen
+  Ce script restaure l'écran de verouillage par défaut de Windows 10
+  Il requiert les droits administrateur.
+
+generate-manual
+  Ce script sauvegarde le mode d'emploi en ligne de commande dans un fichier texte,
+  que vous pouvez utiliser comme référence pour vos scripts Batch ou PowerShell.
+
+hide-console
+  Ce script démarre un autre script sans afficher la fenêtre de l'invite de commande.
+  Il est utile principalement si vous souhaitez planfier un script à l'ouverture de session.
+  Le chemin passé en argument ne devrait pas contenir de caractères spéciaux.
+
+=========================================
+ Planifier l'exécution d'un script batch
+=========================================
+
+Si vous souhaitez mettre à jour votre fond d'écran ou écran de verouillage périodiquement,
+vous pouvez planifier l'exécution d'un script fourni en suivant ces instructions :
+
+= Si vous n'avez pas les droits Administrateur =
+= Méthode du raccourci dans le menu Démarrage =
+
+Utilisez le raccourci clavier Win+R et spéciez:
+  %appdata%\Microsoft\Windows\Start Menu\Programs\Startup
+
+Faite un clic droit à un endroit vide du dossier Démarrage > Nouveau > Raccourci
+  wscript "C:\Chemin\Vers\hide-console.vbs" "C:\Chemin\Vers\votre-script.bat"
+  Suivant > Saisir un nom explicite pour le raccourci > Terminer
+
+Le raccourci sera lancé à l'ouverture de session, ce qui exécutera le script.
+Note: Les scripts pour l'écran de verouillage ne fonctionneront pas via cette méthode.
+
+= Si vous avez les droits Administrateur =
+= Méthode du planificateur de tâches =
+
+Utilisez le raccourci clavier Win+R et spéciez:
+  taskschd.msc
+
+Cliquez sur "Créer une tâche..."
+  Onglet Général
+    - Definir un nom pour la tâche
+    - Cocher "Exécuter avec les autorisations maximales" si vous désirez
+      lancer le script en tant qu'Administrateur (écran de verouillage...)
+  Onglet Déclencheurs
+    - Cliquer sur Nouveau et ajouter un déclencheur
+      "À l'ouverture de session" ou "À l'heure programmée", par exemple.
+  Onglet Actions
+    - Cliquer sur Nouveau, choisir Démarrer un programme
+    - Programme/Script: wscript
+    - Ajouter des arguments: "C:\Chemin\Vers\hide-console.vbs" "C:\Chemin\Vers\votre-script.bat"
+  Onglet Conditions
+    - À votre convenance, décocher "Ne démarrer la tâche que si l'ordinateur est relié au secteur"
+  Onglet Paramètres
+    - Si votre tâche a une heure planifier, par ex 10h tous les jours, mais que votre ordinateur
+      est éteint, la tâche ne s'exécutera pas. Vous pouvez activer l'option "Exécuter la
+      tâche dès que possible si un démarrage planifié est manqué" pour y remédier.
+
+Cliquez sur OK pour sauvegarder votre tâche.
+
+=====
+ FAQ
+=====
+
+Q: L'écran de verrouillage n'apparaît pas lorsque j'ai ouvert ma session ?
+R: Assurez-vous que l'image est également sélectionnée dans vos paramètres personnels d'écran de verouillage.
+
++---------------+
+| © 2018 ORelio |
++---------------+

README.md

@@ -0,0 +1,72 @@
+# SpotlightDL
+
+This program can retrieve Windows Spotlight images by requesting the Microsoft Spotlight API.
+SpotlightDL can also define images as wallpaper and system-wide lockscreen image.
+
+It is useful in the following use cases:
+ - Download the whole Spotlight library with maximum image resolution and metadata
+ - Define Spotlight images as wallpaper, not only on Windows 10 but also on previous versions
+ - Define Spotlight images as global lock screen: without ads, and without any user being logged in
+ - Chain SpotlightDL with your own scripts and apps by taking advantage of the url mode
+
+# How to use
+
+Simply call `SpotlightDownloader.exe` from the Windows command prompt and see usage.
+The download/url modes should also work on Mac/Linux using the Mono framework.
+
+A few Batch files are offered for ease of use for common tasks:
+
+ - spotlight-download: Download Spotlight images
+ - update-wallpaper: Set images as desktop wallpaper
+ - update-lockscreen: Set images as system-wide lockscreen
+ - restore-lockscreen: Restore default system-wide lockscreen
+ - generate-manual: Generate a text file with command-line usage
+
+If you wish to periodically update your wallpaper or lockscreen,
+you can schedule one of the provided script by following [these instructions](README-En.txt).
+
+# How it works
+
+## Spotlight API
+
+The Spotlight API is located on the following endpoint:
+
+`https://arc.msn.com/v3/Delivery/Cache?pid=209567&fmt=json&rafb=0&ua=WindowsShellClient%2F0&disphorzres=9999&dispvertres=9999&lo=80217&pl=en-US&lc=en-US&ctry=us&time=2017-12-31T23:59:59Z`
+
+Where the expected arguments are:
+ - `pid` : Purpose currently unknown
+ - `fmt` : Output format, e.g. `json`
+ - `rafb` : Purpose currently unknown
+ - `ua` : Client user agent string
+ - `disphorzres`: Screen width in pixels
+ - `dispvertres`: Screen height in pixels
+ - `lo` : Purpose currently uknown
+ - `pl` : Locale, e.g. `en-US`
+ - `lc` : Language, e.g. `en-US`
+ - `ctry` : Country, e.g. `us`
+ - `time` : Time, e.g. `2017-12-31T23:59:59Z`
+
+The JSON response contains details about 6-7 images including image url, title, sha256, ads, etc.
+
+Spotlight API URL was originally found in this [file](https://github.com/KoalaBR/spotlight/blob/3164a43684dcadb751ce9a38db59f29453acf2fe/spotlightprovider.cpp#L17), thanks to the author for their findings!
+
+## Global lock screen
+
+The global lock screen image is stored as `C:\Windows\Web\Screen\img100.jpg`.
+SpotlightDL backups the image as `img200.jpg` if it does not already exists, then overwrite this file.
+The lock screen image cache, located at `C:\ProgramData\Microsoft\Windows\SystemData\S-1-5-18\ReadOnly\LockScreen_Z`, must be cleared for the change to take effect.
+
+SpotlightDL gets around NTFS permissions on these folders [being locked down to TrustedInstaller](https://helpdeskgeek.com/windows-7/windows-7-how-to-delete-files-protected-by-trustedinstaller/)
+by setting the local `Administrators` group as new owner of the relevant files and folders, and granting full control to this group.
+Then, programs running as administrator can overwrite the lockscreen image and clear the cache.
+
+This way of replacing the lockscreen is basically a C# implementation of [this script](https://www.reddit.com/r/PowerShell/comments/5fglby/powershell_to_set_windows_10_lockscreen/daoepvj/),
+avoiding the use of the `takeown` and `iacls` commands which are not reliable due to a [localization issue](http://community.idera.com/powershell/ask_the_experts/f/powershell_for_windows-12/10227/trying-to-make-a-takeown-exe-cmdlet-but-locales-is-causing-a-problem).
+
+# License
+
+SpotlightDL is provided under [CDDL-1.0](http://opensource.org/licenses/CDDL-1.0) ([Why?](http://qstuff.blogspot.fr/2007/04/why-cddl.html)).
+
+Basically, you can use it or its source for any project, free or commercial, but if you improve it or fix issues,
+the license requires you to contribute back by submitting a pull request with your improved version of the code.
+Also, credit must be given to the original project, and license notices may not be removed from the code.

Scripts/generate-manual.bat

@@ -0,0 +1,7 @@
+@echo off
+cd "%~dp0"
+
+:: This script saves usage info as a text file for convenience
+
+SpotlightDownloader > Manual.txt 2>&1
+start Notepad Manual.txt

Scripts/hide-console.vbs

@@ -0,0 +1,19 @@
+' taken from FreeFileSync - www.freefilesync.org
+
+set argIn = WScript.Arguments
+num = argIn.Count
+
+if num = 0 then
+    WScript.Echo "Call a Windows batch file (*.cmd, *.bat) without showing the console window" & VbCrLf & VbCrLf &_
+                 "Command line:" & VbCrLf & "WScript HideConsole.vbs MyBatchfile.cmd <command line arguments>"
+    WScript.Quit 1
+end if
+
+argOut = ""
+for i = 0 to num - 1
+    argOut = argOut & """" & argIn.Item(i) & """ "
+next
+
+set WshShell = WScript.CreateObject("WScript.Shell")
+
+WshShell.Run argOut, 0, True

Scripts/restore-lockscreen.bat

@@ -0,0 +1,15 @@
+@echo off
+cd "%~dp0"
+
+:: This script restores the default lock screen image from Windows 10.
+:: SpotlightDownloader performs a backup before overwriting the file,
+:: so we just need to define the backup file as lockscreen image.
+
+net session > nul 2>&1
+if not "%errorlevel%" == "0" (
+    echo Please run me as administrator^!
+    pause > nul
+    exit
+)
+
+SpotlightDownloader lockscreen --from-file "%systemroot%\Web\Screen\img200.jpg"

Scripts/spotlight-download.bat

@@ -0,0 +1,11 @@
+@echo off
+cd "%~dp0"
+
+:: This script downloads as much images as possible from the Spotlight API,
+:: with maximum res and metadata. Please note that there is no actual way
+:: of listing *all* images so SpotlightDownloader will make many API calls
+:: to discover and download new images, and stop when no new images are
+:: discovered. It may miss a few images but you should get most of them.
+
+mkdir SpotlightArchive > nul 2>&1
+SpotlightDownloader download --many --maxres --metadata --outdir SpotlightArchive

Scripts/update-lockscreen.bat

@@ -0,0 +1,33 @@
+@echo off
+cd "%~dp0"
+
+:: This script maintains a cache of 6-7 Spotlight pictures
+:: and randomly defines a new Spotlight image as lockscreen
+
+net session > nul 2>&1
+if not "%errorlevel%" == "0" (
+    echo Please run me as administrator^!
+    pause > nul
+    exit
+)
+
+:: The Spotlight directory will hold a cache of 6-7 images
+:: for performing lockscreen updates without Internet access
+
+mkdir SpotlightCache > nul 2>&1
+
+:: Try retrieving a new set of images using a temporary directory
+:: In case of success, old images are replaced with new ones
+
+mkdir SpotlightCache2 > nul 2>&1
+SpotlightDownloader download --metadata --outdir SpotlightCache2
+if "%errorlevel%" == "0" (
+    del /Q SpotlightCache\*
+    move SpotlightCache2\* SpotlightCache\
+)
+rmdir SpotlightCache2
+
+:: Regardless of whether the cache was updated, we pick a new pic
+:: That way, the lockscreen gets updated even without Internet access
+
+SpotlightDownloader lockscreen --from-dir SpotlightCache