Constants

STATUS_INSTANCE_CREATING

STATUS_INSTANCE_CREATING

Instance is being created.

STATUS_INSTANCE_ACTIVE

STATUS_INSTANCE_ACTIVE

Instance is active and configuration is valid.

STATUS_INSTANCE_DELETING

STATUS_INSTANCE_DELETING

Instance is being deleted.

STATUS_INSTANCE_INACTIVE

STATUS_INSTANCE_INACTIVE

Instance is inactive (ie. disabled).

STATUS_INSTANCE_NOT_CREATED

STATUS_INSTANCE_NOT_CREATED

Instance is not yet created.

DEBUG_TEXT

DEBUG_TEXT

Use plain text for debug message.

DEBUG_HEX

DEBUG_HEX

Use hex for debug message.

Properties

$library

$library : \Patami\IPS\Libraries\Library

Type

\Patami\IPS\Libraries\Library — IPS library object instance to which this module belongs to.

Methods

__construct()

__construct(integer  $instanceId) 

Module constructor.

Creates a new object of the IPS module instance. This method is automatically called by IPS when one of the registered functions are called or when the instance is used by IPS in any other way (eg. when creating the instance or when opening the configuration form).

Parameters

integer $instanceId

IPS object ID of the instance.

Create()

Create() 

Registers configuration properties and timers.

Destroy()

Destroy() 

Performs cleanup tasks when the instance is deleted.

GetConfigurationForm()

GetConfigurationForm() : string

Returns the IPS module configuration form data as a JSON-encoded array.

This method will call Module::GetConfigurationFormData(), which returns an array with the configuration form elements, actions and translations. The array returned by the method is JSON-encoded and returned to IPS. The method adds a couple of form fields to the form, including module information and copyright information and two buttons which open the module documentation and release notes web pages.

Returns

string —

JSON-encoded configuration form data.

ApplyChanges()

ApplyChanges() 

Performs actions required when the configuration of this instance was saved.

It is automatically called by IPS when the use presses the apply button on the instance's configuration page and calls the Module::Configure() method which can be overridden by your own modules.

GetId()

GetId() : integer

Returns the IPS object ID of the instance.

Returns

integer —

IPS object ID of the instance.

GetInstance()

GetInstance() : \Patami\IPS\Objects\Instance

Returns an Instance object for the module instance.

Returns

\Patami\IPS\Objects\Instance

Instance object for the instance.

GetModuleId()

GetModuleId() : string

Returns the IPS module GUID of the module.

Returns

string —

IPS module GUID.

GetModuleName()

GetModuleName() : string

Returns the name of the module.

Returns

string —

Name of the module.

GetModuleInstances()

GetModuleInstances() : array

Returns a list of all IPS object IDs of all instances of the module.

Returns

array —

IPS object IDs of all instances of the module.

IsValid()

IsValid() : boolean

Checks if the instance if valid / active.

Returns

boolean —

True if the instance is active.

GetParentId()

GetParentId() : integer

Returns the IPS object ID of the parent IPS instance.

The parent instance is not the instance above the current instance in the IPS object tree, but the instance to which this instance is connected to.

Returns

integer —

IPS object ID of the parent instance.

IsParentActive()

IsParentActive() : boolean

Checks if the parent IPS instance is active.

Returns

boolean —

True if the parent IPS instance is active.

MessageSink()

MessageSink(integer  $timestamp, integer  $senderId, integer  $messageId, array  $data) 

Processes IPS messages.

This method is called by IPS for registered messages when they are triggered.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

integer $senderId

IPS object ID of the object that that triggered the message.

integer $messageId

ID of the message.

array $data

Event data.

SendEncodedDataToParent()

SendEncodedDataToParent(string  $dataId, array|mixed  $data) : string|null

Sends data to the parent IPS instance.

The data is received by the parent instance's IPSModule::ForwardData() method.

Parameters

string $dataId

GUID of the data packet type.

array|mixed $data

Data which should be encoded in the data packet.

Returns

string|null —

Result returned from the IPSModule::ForwardData() method.

SendEncodedDataToChildren()

SendEncodedDataToChildren(string  $dataId, array|mixed  $data) 

Sends data to all child IPS instances.

The data is received by the child instance's IPSModule::ReceiveData() method.

Parameters

string $dataId

GUID of the data packet type.

array|mixed $data

Data which should be encoded in the data packet.

RegisterVariableBoolean()

RegisterVariableBoolean(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new boolean status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the variable profile and the position of the variable, but not its name.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableBooleanEx()

RegisterVariableBooleanEx(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new boolean status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the name, the variable profile and the position of the variable.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableFloat()

RegisterVariableFloat(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new float status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the variable profile and the position of the variable, but not its name.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableFloatEx()

RegisterVariableFloatEx(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new float status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the name, the variable profile and the position of the variable.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableInteger()

RegisterVariableInteger(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new integer status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the variable profile and the position of the variable, but not its name.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableIntegerEx()

RegisterVariableIntegerEx(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new integer status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the name, the variable profile and the position of the variable.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableString()

RegisterVariableString(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new string status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the variable profile and the position of the variable, but not its name.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableStringEx()

RegisterVariableStringEx(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new string status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the name, the variable profile and the position of the variable.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

ShowSupportInfo()

ShowSupportInfo() 

Displays support info to the user.

Debug()

Debug(  $tag,   $message, array  $data = null) 

Parameters

$tag
$message
array $data

DebugEx()

DebugEx(string  $tag, string  $message, array|null  $data = null) : $this

Sends an extended debug message to the log.

Parameters

string $tag

Name of the sender of the log (can be used as a category or similar).

string $message

The log message.

array|null $data

Optional data to be added to the log entry.

Returns

$this —

Fluent interface.

GetClassFileName()

GetClassFileName() : string

Returns the file name of the class.

It always returns the name of the called class.

Returns

string —

File name of the class.

GetModuleDirectory()

GetModuleDirectory() : string

Returns the directory name of the module class file.

Returns

string —

Directory name of the class.

GetModuleInfoFileName()

GetModuleInfoFileName() 

GetLibraryName()

GetLibraryName() : string

Returns the key of the library to which the module belongs to.

Returns

string —

Key of the library.

GetConfigurationFormData()

GetConfigurationFormData() : array

Returns the IPS module configuration form data.

This convenience method returns an array with the configuration form data, while IPS' default method Module::GetConfigurationForm() is expected to return an JSON-encoded array. An implementation of this method in concrete module classes should call the parent method and then add their own form fields to the data structure returned by the base method. Also note that the form data may also contain translations, which is not mentioned in the IPS documentation.

Returns

array —

IPS module configuration form data.

Configure()

Configure() 

Performs actions required when the configuration of this instance was saved.

It is automatically called by the Module::ApplyChanges() method, which is in turn automatically called by IPS when the user presses the apply button on the instance's configuration page. You should call parent::Configure() at the end of the overridden method, in case the configuration of the instance is OK. Otherwise set a different instance status and do not call the parent method.

GetModuleFileInfo()

GetModuleFileInfo() : array

Returns information about the module from the module.json file.

Returns

array —

Attributes of the module.

GetModulePrefix()

GetModulePrefix() : string

Returns the prefix used by IPS to register the public module methods / functions.

Returns

string —

Function prefix.

IsPrivate()

IsPrivate() : boolean

Checks if the module is private.

A module is regarded as being private if its library is not loaded anonymously.

Returns

boolean —

True if the module is private.

ListenForInstanceReloads()

ListenForInstanceReloads(integer  $instanceId) 

Registers an instance to listen for reload events.

Parameters

integer $instanceId

IPS object ID of the other instance.

OnKernelStarted()

OnKernelStarted(integer  $timestamp, array  $data) 

Event handler called when the IPS kernel started.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

array $data

Event data.

OnKernelShutdown()

OnKernelShutdown(integer  $timestamp, array  $data) 

Event handler called when the IPS kernel is about to shutdown.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

array $data

Event data.

OnInstanceConnect()

OnInstanceConnect(integer  $timestamp, integer  $senderId, array  $data) 

Event handler called when another instance interface is connected.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

integer $senderId

IPS object ID of the object that that triggered the message.

array $data

Event data.

OnMessage()

OnMessage(integer  $timestamp, integer  $senderId, integer  $messageId, array  $data) 

Processes IPS messages.

This method is called by the frameork for registered messages when they are triggered.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

integer $senderId

IPS object ID of the object that that triggered the message.

integer $messageId

ID of the message.

array $data

Event data.

GetEncodedData()

GetEncodedData(string  $dataId, array  $data) : string

Encodes data to be send to child or parent IPS instances.

Parameters

string $dataId

GUID of the data packet type.

array $data

Data which should be encoded in the data packet.

Returns

string —

JSON-encoded data to be sent to child or parent IPS instances.

GetSupportInfo()

GetSupportInfo() : array

Returns support info to be displayed to the user.

Returns

array —

Key value pairs with support info.

GetLicenseUrl()

GetLicenseUrl() : string|null

Returns the URL the the module's license web page.

Override this method in your module to link to your own license.

Returns

string|null —

URL to the module's license web page or null if the button to open the web page should not be displayed in the module's configuration form.

GetNewIssueUrl()

GetNewIssueUrl() : string|null

Returns the URL to open a new issue in the module's issue tracker.

Override this method in your module to link to your issue tracker.

Returns

string|null —

URL to the create issue web page of your issue tracker or null if the button to open a new issue should not be displaxed in the module's configuration form.

GetDocumentationUrl()

GetDocumentationUrl() : string|null

Returns the URL to the module's documentation web page.

Override this method in your module to link to your own documentation.

Returns

string|null —

URL to the module's documentation web page or null if the button to open the web page should not be displayed in the module's configuration form.

GetReleaseNotesUrl()

GetReleaseNotesUrl() : string|null

Returns the URL to the module's release notes web page.

Override this method in your module to link to your own release notes.

Returns

string|null —

URL to the module's release notes web page or null if the button to open the web page should not be displayed in the module's configuration form.