updates.h File Reference

Game and content update handler functions. More...

Go to the source code of this file.

Enumerations
enum	updateType_t {   UPDATE_NAME , UPDATE_CATEGORY , UPDATE_TITLE , UPDATE_VERSION ,   UPDATE_DESCRIPTION , UPDATE_LICENSE , UPDATE_AUTHOR , UPDATE_WEBSITE ,   UPDATE_STATE , UPDATE_ACTION , UPDATE_FILESIZE , UPDATE_PREVIEWIMAGE ,   UPDATE_STATUSSTRING , UPDATE_DLPERCENTAGE }
	Different types you can pass to Updates_GetInfo(...) to learn details about a given Update entry. More...
enum	updateState_t {   UPDATESTATE_NONE , UPDATESTATE_DISABLED , UPDATESTATE_ENABLED , UPDATESTATE_CORRUPT ,   UPDATESTATE_PENDING }
	Return values from passing UPDATE_STATE to Updates_GetInfo() More...
enum	updateAction_t {   UPDATEACTION_NONE , UPDATEACTION_INSTALL , UPDATEACTION_REINSTALL , UPDATEACTION_UNINSTALL ,   UPDATEACTION_AUTOINSTALL , UPDATEACTION_DISABLE , UPDATEACTION_RETAIN }
	Return values from passing UPDATE_ACTION to Updates_GetInfo() More...
enum	updaterStatus_t { UPDATER_NONE , UPDATER_UNAVAILABLE , UPDATER_PENDING , UPDATER_INITIALIZED }
	These are the possible return values from Updates_GetUpdaterStatus(). More...

Functions
void	Updates_Init (void)
	Call this in order to contact the update server and fill the list of updates. More...
updaterStatus_t	Updates_GetUpdaterStatus (void)
	Retrieve the status of the updater. More...
int	Updates_GetPackageCount (void)
	Returns the total amount of updates available for the currently running game. More...
__variant	Updates_GetInfo (int, updateType_t)
	Query a package (by ID) for its various info fields. More...
bool	Updates_Available (void)
	Returns if our current game has updates available for any installed packages. More...
bool	Updates_Toggle (int)
	Toggle the installation/disabling of an update. More...
bool	Updates_Install (int)
	Mark an update as pending installion. More...
bool	Updates_Remove (int)
	Mark an update as pending deletion. More...
bool	Updates_Destroy (int)
	Mark an update as pending uninstallation. More...
bool	Updates_ApplyPendingChanges (void)
	Apply all pending changes to packages. More...

Detailed Description

Game and content update handler functions.

The updater is an abstraction of the engine its own package manager. Not all packages the engine offers are related to the game you're currently running. Therefore we offer our own API within Nuclide to deal with game updates.

You want to call Updates_Init() once, after which Updates_GetUpdaterStatus() should be queried to determine when the Updater is ready. That is not necessary, but it might be helpful to throw up a loading screen while that is returning UPDATER_PENDING.

Once Updates_GetUpdaterStatus() reports UPDATER_INITIALIZED, you can expect the loading to be fully done.

The function Updates_GetPackageCount() will report the total amount of update packages available for the game. These are not 'new' updates, they contain every package associated with the game that can and should be installed and kept updated.

Use Updates_GetInfo() to retrieve metadata about individual packages.

Enumeration Type Documentation

updateAction_t

enum updateAction_t

Return values from passing UPDATE_ACTION to Updates_GetInfo()

Enumerator
UPDATEACTION_NONE	Update is not marked for any change.
UPDATEACTION_INSTALL	Update marked for installation.
UPDATEACTION_REINSTALL	Update marked as needing re-installation.
UPDATEACTION_UNINSTALL	Update marked for removal.
UPDATEACTION_AUTOINSTALL	Update marked as needing to be installed, due to a dependency.
UPDATEACTION_DISABLE	Update has been marked for disabling.
UPDATEACTION_RETAIN	Update has been marked as being retained.

updaterStatus_t

enum updaterStatus_t

These are the possible return values from Updates_GetUpdaterStatus().

That way you can put up a loading screen for when the updater is still initiliazing, or be notified of when an updater is not available at all.

Enumerator
UPDATER_NONE	Nuclide's updater has not been initialized. You need to call Update_Init().
UPDATER_UNAVAILABLE	Nuclide's updater is unavailable. This may be due to the update server being offline.
UPDATER_PENDING	Nuclide's updater is pending. May change to UNAVAILABLE or INITIALIZED.
UPDATER_INITIALIZED	Nuclide's updater is initialized and may have entries. Use Updates_GetUpdateCount() to query how many.

updateState_t

enum updateState_t

Return values from passing UPDATE_STATE to Updates_GetInfo()

Enumerator
UPDATESTATE_NONE	Update is not installed, or unavailable.
UPDATESTATE_DISABLED	Update is installed, but disabled.
UPDATESTATE_ENABLED	Update is installed and enabled.
UPDATESTATE_CORRUPT	Update on disk is corrupted.
UPDATESTATE_PENDING	Update is pending a change. Usually when we're downloading it.

updateType_t

enum updateType_t

Different types you can pass to Updates_GetInfo(...) to learn details about a given Update entry.

Enumerator
UPDATE_NAME	(string) name of the package, for use with the pkg command.
UPDATE_CATEGORY	(string) category text
UPDATE_TITLE	(string) name of the package, for showing the user.
UPDATE_VERSION	(string) version info (may have multiple with the same name but different versions)
UPDATE_DESCRIPTION	(string) some blurb
UPDATE_LICENSE	(string) what license its distributed under
UPDATE_AUTHOR	(string) name of the person(s) who created it
UPDATE_WEBSITE	(string) where to contribute/find out more info/etc
UPDATE_STATE	(updateState_t) The current state of the update.
UPDATE_ACTION	(updateAction_t) Pending action of the update.
UPDATE_FILESIZE	(int) size to download in bytes.
UPDATE_PREVIEWIMAGE	(string) Path to a preview image in 4:3 aspect ratio.
UPDATE_STATUSSTRING	(string) Localizable string that gives you the update status.
UPDATE_DLPERCENTAGE	(float) Download progress in percent (0-100).

Function Documentation

Updates_ApplyPendingChanges()

bool Updates_ApplyPendingChanges

(

void

)

Apply all pending changes to packages.

May return true/false if it succeeded in doing so.

Updates_Available()

bool Updates_Available

(

void

)

Returns if our current game has updates available for any installed packages.

Updates_Destroy()

bool Updates_Destroy

(

int

packageID

)

Mark an update as pending uninstallation.

May return true/false if it succeeded in marking the package.

Updates_GetInfo()

__variant Updates_GetInfo	(	int	packageID,
		updateType_t	fieldType
	)

Query a package (by ID) for its various info fields.

See updateType_t for available fields.

Updates_GetPackageCount()

int Updates_GetPackageCount

(

void

)

Returns the total amount of updates available for the currently running game.

Updates_GetUpdaterStatus()

updaterStatus_t Updates_GetUpdaterStatus

(

void

)

Retrieve the status of the updater.

See updaterStatus_t for valid return values.

Updates_Init()

void Updates_Init

(

void

)

Call this in order to contact the update server and fill the list of updates.

Updates_Install()

bool Updates_Install

(

int

packageID

)

Mark an update as pending installion.

May return true/false if it succeeded in marking the package.

Updates_Remove()

bool Updates_Remove

(

int

packageID

)

Mark an update as pending deletion.

May return true/false if it succeeded in marking the package.

Updates_Toggle()

bool Updates_Toggle

(

int

packageID

)

Toggle the installation/disabling of an update.

May return true/false if it succeeded in marking the package.