README
¶
WinSparkle Go Bindings
This package provides go bindings for WinSparkle created by Vaclav Slavik.
WinSparkle is a plug-and-forget software update library for Windows applications. It is heavily inspired by the Sparkle framework for OS X written by Andy Matuschak and others, to the point of sharing the same updates format (appcasts) and having very similar user interface.
See https://winsparkle.org for more information about WinSparkle.
Documentation
See the WinSparkle wiki and the GoDoc.
Important
WinSparkle.dll must be placed into the same directory as your app executable. Depending on your architecture use the version from dll/x64, dll/x86 or dll/arm64.
Alternatively you can embed the DLL into your application by importing
github.com/abemedia/go-winsparkle/dll.
Example
package main
import (
"github.com/abemedia/go-winsparkle"
_ "github.com/abemedia/go-winsparkle/dll" // Embed DLL.
)
func main() {
sparkle.SetAppcastURL("https://dl.example.com/appcast.xml")
sparkle.SetAppDetails("example.com", "My Cool App", "1.0.0")
sparkle.SetAutomaticCheckForUpdates(true)
if err := sparkle.SetDSAPubPEM(dsaPublicKey); err != nil {
panic(err)
}
// Start your app before initiating WinSparkle.
runMyApp()
winsparkle.Init()
defer winsparkle.Cleanup()
}
Documentation
¶
Overview ¶
Package winsparkle provides go bindings for WinSparkle.
WinSparkle is a plug-and-forget software update library for Windows applications. It is heavily inspired by the Sparkle framework for OS X written by Andy Matuschak and others, to the point of sharing the same updates format (appcasts) and having a very similar user interface.
See https://winsparkle.org for more information about WinSparkle.
Index ¶
- func CheckUpdateWithUI()
- func CheckUpdateWithUIAndInstall()
- func CheckUpdateWithoutUI()
- func Cleanup()
- func ClearHTTPHeaders()
- func GetAutomaticCheckForUpdates() bool
- func GetLastCheckTime() time.Time
- func GetUpdateCheckInterval() time.Duration
- func Init()
- func SetAppBuildVersion(build string)
- func SetAppDetails(company, app, version string)
- func SetAppcastURL(url string)
- func SetAutomaticCheckForUpdates(check bool)
- func SetCanShutdownCallback(cb func() bool)
- func SetConfigMethods(store ConfigStore)
- func SetDSAPubPEM(pem string) error
- func SetDidFindUpdateCallback(cb func())
- func SetDidNotFindUpdateCallback(cb func())
- func SetErrorCallback(cb func())
- func SetHTTPHeader(name, value string)
- func SetLang(lang string)
- func SetLangID(langid uint16)
- func SetRegistryPath(path string)
- func SetShutdownRequestCallback(cb func())
- func SetUpdateCancelledCallback(cb func())
- func SetUpdateCheckInterval(interval time.Duration)
- func SetUpdateDismissedCallback(cb func())
- func SetUpdatePostponedCallback(cb func())
- func SetUpdateSkippedCallback(cb func())
- func SetUserRunInstallerCallback(cb func(file string) (handled bool, err error))
- type ConfigStore
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckUpdateWithUI ¶
func CheckUpdateWithUI()
CheckUpdateWithUI checks if an update is available, showing progress UI to the user.
Normally, WinSparkle checks for updates on startup and only shows its UI when it finds an update. If the application disables this behavior, it can hook this function to "Check for updates..." menu item.
When called, background thread is started to check for updates. A small window is shown to let the user know the progress. If no update is found, the user is told so. If there is an update, the usual "update available" window is shown.
This function returns immediately.
Note: Because this function is intended for manual, user-initiated checks for updates, it ignores "Skip this version" even if the user checked it previously.
func CheckUpdateWithUIAndInstall ¶
func CheckUpdateWithUIAndInstall()
CheckUpdateWithUIAndInstall checks if an update is available, showing progress UI to the user and immediately installing the update if one is available.
This is useful for the case when users should almost always use the newest version of your software. When called, WinSparkle will check for updates showing a progress UI to the user. If an update is found the update prompt will be skipped and the update will be installed immediately.
If your application expects to do something after checking for updates you may wish to use SetDidNotFindUpdateCallback and SetUpdateCancelledCallback.
func CheckUpdateWithoutUI ¶
func CheckUpdateWithoutUI()
CheckUpdateWithoutUI checks if an update is available.
No progress UI is shown to the user when checking. If an update is available, the usual "update available" window is shown; this function is *not* completely UI-less.
Use with caution, it usually makes more sense to use the automatic update checks on interval option or manual check with visible UI.
This function returns immediately.
Note: This function respects "Skip this version" choice by the user.
func Cleanup ¶
func Cleanup()
Cleanup cleans up after WinSparkle.
Should be called by the app when it's shutting down. Cancels any pending Sparkle operations and shuts down its helper threads.
func ClearHTTPHeaders ¶
func ClearHTTPHeaders()
ClearHTTPHeaders clears all custom HTTP headers previously added using SetHTTPHeader.
func GetAutomaticCheckForUpdates ¶
func GetAutomaticCheckForUpdates() bool
GetAutomaticCheckForUpdates gets the automatic update checking state.
Returns true if updates are set to be checked automatically, false otherwise.
Note: Defaults to 0 when not yet configured (as happens on first start).
func GetLastCheckTime ¶
GetLastCheckTime gets the time for the last update check.
Default value is -1, indicating that the update check has never run.
func GetUpdateCheckInterval ¶
GetUpdateCheckInterval gets the automatic update interval.
Default value is one day.
func Init ¶
func Init()
Init starts WinSparkle.
If WinSparkle is configured to check for updates on startup, proceeds to perform the check. You should only call this function when your app is initialized and shows its main window.
This call doesn't block and returns almost immediately. If an update is available, the respective UI is shown later from a separate thread.
func SetAppBuildVersion ¶
func SetAppBuildVersion(build string)
SetAppBuildVersion sets application build version number.
This is the internal version number that is not normally shown to the user. It can be used for finer granularity that official release versions, e.g. for interim builds.
If this function is called, then the provided *build* number is used for comparing versions; it is compared to the "version" attribute in the appcast and corresponds to OS X Sparkle's CFBundleVersion handling. If used, then the appcast must also contain the "shortVersionString" attribute with human-readable display version string. The version passed to SetAppDetails corresponds to this and is used for display.
func SetAppDetails ¶
func SetAppDetails(company, app, version string)
SetAppDetails sets application metadata.
Normally, these are taken from VERSIONINFO/StringFileInfo resources, but if your application doesn't use them for some reason, using this function is an alternative.
`app` is both shown to the user and used in HTTP User-Agent header.
Note: `company` and `app` are used to determine the location of WinSparkle settings in registry (HKCU\Software\<company>\<app>\WinSparkle is used).
func SetAppcastURL ¶
func SetAppcastURL(url string)
SetAppcastURL sets URL for the app's appcast.
Only http and https schemes are supported.
If this function isn't called by the app, the URL is obtained from Windows resource named "FeedURL" of type "APPCAST".
Note: Always use HTTPS feeds, do not use unencrypted HTTP! This is necessary to prevent both leaking user information and preventing various MITM attacks.
Note: See https://github.com/vslavik/winsparkle/wiki/Appcast-Feeds for more information about appcast feeds.
func SetAutomaticCheckForUpdates ¶
func SetAutomaticCheckForUpdates(check bool)
SetAutomaticCheckForUpdates sets whether updates are checked automatically or only through a manual call. If disabled, CheckUpdateWithUI must be used explicitly.
func SetCanShutdownCallback ¶
func SetCanShutdownCallback(cb func() bool)
SetCanShutdownCallback sets callback for querying the application if it can be closed.
This callback will be called to ask the host if it's ready to shut down, before attempting to launch the installer. The callback returns `true` if the host application can be safely shut down or `false` if not (e.g. because the user has unsaved documents).
func SetConfigMethods ¶
func SetConfigMethods(store ConfigStore)
SetConfigMethods overrides WinSparkle's configuration read, write and delete functions.
By default, WinSparkle will read, write and delete configuration values by interacting directly with Windows Registry. If you want to manage configuration by yourself, or if you don't want let WinSparkle write settings directly to the Windows Registry, you can provide your own functions to read, write and delete configuration.
func SetDSAPubPEM ¶
SetDSAPubPEM sets DSA public key.
Only PEM format is supported.
Public key will be used to verify DSA signature of the update file. PEM data will be set only if it contains valid DSA public key.
If this function isn't called by the app, public key is obtained from Windows resource named "DSAPub" of type "DSAPEM".
func SetDidFindUpdateCallback ¶
func SetDidFindUpdateCallback(cb func())
SetDidFindUpdateCallback sets callback to be called when the updater did find an update.
This is useful in combination with CheckUpdateWithUIAndInstall as it allows you to perform some action after WinSparkle checks for updates.
func SetDidNotFindUpdateCallback ¶
func SetDidNotFindUpdateCallback(cb func())
SetDidNotFindUpdateCallback sets callback to be called when the updater did not find an update.
This is useful in combination with CheckUpdateWithUIAndInstall as it allows you to perform some action after WinSparkle checks for updates.
func SetErrorCallback ¶
func SetErrorCallback(cb func())
SetErrorCallback sets callback to be called when the updater encounters an error.
func SetHTTPHeader ¶
func SetHTTPHeader(name, value string)
SetHTTPHeader sets custom HTTP header for appcast checks.
func SetLang ¶
func SetLang(lang string)
SetLang sets UI language from its ISO code.
This function must be called before Init.
Param lang must be an ISO 639 language code with an optional ISO 3116 country code, e.g. "fr", "pt-PT", "pt-BR" or "pt_BR", as used e.g. by ::GetThreadPreferredUILanguages() too.
func SetLangID ¶
func SetLangID(langid uint16)
SetLangID sets UI language from its Win32 LANGID code.
This function must be called before Init.
Param langid must be a Language code (LANGID) as created by the MAKELANGID macro or returned by e.g. ::GetThreadUILanguage().
func SetRegistryPath ¶
func SetRegistryPath(path string)
SetRegistryPath sets the registry path where settings will be stored.
Normally, these are stored in "HKCU\Software\<company_name>\<app_name>\WinSparkle" but if your application needs to store the data elsewhere for some reason, using this function is an alternative.
Note that `path` is relative to HKCU/HKLM root and the root is not part of it. For example:
sparkle.SetRegistryPath("Software\\My App\\Updates");
func SetShutdownRequestCallback ¶
func SetShutdownRequestCallback(cb func())
SetShutdownRequestCallback sets callback for shutting down the application.
This callback will be called to ask the host to shut down immediately after launching the installer. Its implementation should gracefully terminate the application.
func SetUpdateCancelledCallback ¶
func SetUpdateCancelledCallback(cb func())
SetUpdateCancelledCallback sets callback to be called when the user cancels a download.
This is useful in combination with CheckUpdateWithUIAndInstall as it allows you to perform some action when the installation is interrupted.
func SetUpdateCheckInterval ¶
SetUpdateCheckInterval sets the automatic update interval between checks for updates.
Note: The minimum update interval is 1 hour.
func SetUpdateDismissedCallback ¶
func SetUpdateDismissedCallback(cb func())
SetUpdateDismissedCallback sets callback to be called when the user dismisses (closes) update dialog.
This is useful in combination with CheckUpdateWithoutUI or similar as it allows you to perform some action when the update dialog is closed.
func SetUpdatePostponedCallback ¶
func SetUpdatePostponedCallback(cb func())
SetUpdatePostponedCallback sets callback to be called when the user postpones an update (presses 'remind me later' button).
This is useful in combination with CheckUpdateWithUI or similar as it allows you to perform some action when the download is postponed.
func SetUpdateSkippedCallback ¶
func SetUpdateSkippedCallback(cb func())
SetUpdateSkippedCallback sets callback to be called when the user skips an update.
This is useful in combination with CheckUpdateWithUIAndInstall or similar as it allows you to perform some action when the update is skipped.
func SetUserRunInstallerCallback ¶
SetUserRunInstallerCallback sets callback to be called when the update payload is downloaded and read to be executed or handled in some other manner.
The callback returns a boolean indicating whether the update was handled and an error. If `handled` is `false` and there is no error WinSparkle's default handling will take place.
Types ¶
type ConfigStore ¶
type ConfigStore interface {
// Read returns a config value and a bool indicating if it was successful.
Read(name string) (value string, ok bool)
// Write a config value. Returns a bool indicating if it was successful.
Write(name, value string) bool
// Delete config value. Returns a bool indicating if it was successful.
Delete(name string) bool
}
ConfigStore is used to override WinSparkle configuration's read, write and delete functions.
Source Files
Directories