\devices\test_moduleDevice_TestModule

This is the main implementation class of the module

The name of the class must the the 'Device_' followed by the name of the module file (without the '.php' extension), so in this case the file is "TestModule.php" and the class is Device_TestModule.

The class MUST define the constructor method and one additional public method: writeInstaller().

All other methods and properties should be private. This example sets zipInstaller method to protected, so that it can be seen in the documentation.

It is important to understand how the device module fits into the whole picture, so here is s short descrption. An external caller (for instance GUI::generateInstaller()) creates the module device instance and prepares its environment for a given user profile by calling DeviceConfig::setup() method. this will:

  • create the temporary directory and save its path as $this->FPATH
  • process the CA certificates and store results in $this->attributes['internal:CAs'][0] $this->attributes['internal:CAs'][0] is an array of processed CA certificates a processed certifincate is an array 'pem' points to pem feromat certificate 'der' points to der format certificate 'md5' points to md5 fingerprint 'sha1' points to sha1 fingerprint 'name' points to the certificate subject 'root' can be 1 for self-signed certificate or 0 otherwise
  • save the info_file (if exists) and put the name in $this->attributes['internal:info_file_name'][0] Finally, the module DeviceConfig::writeInstaller is called and the returned path name is used for user download.

Summary

Methods
Properties
Constants
__construct()
setup()
calculatePreferredEapType()
writeDeviceInfo()
getAttibute()
writeInstaller()
__destruct()
getAttributeValue()
createTemporaryDirectory()
rrmdir()
uuid()
randomString()
$FPATH
$specialities
$supportedEapMethods
$nomenclature_fed
$nomenclature_inst
$attributes
$module_path
$selectedEap
$selectedEapObject
$sign
$signer
$device_id
$options
$support_email_substitute
$support_url_substitute
$installerBasename
$deviceUUID
L_OK
L_REMARK
L_WARN
L_ERROR
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Constants

L_OK

L_OK = 0

L_REMARK

L_REMARK = 4

L_WARN

L_WARN = 32

L_ERROR

L_ERROR = 256

Properties

$FPATH

$FPATH : 

stores the path to the temporary working directory for a module instance

Type

$specialities

$specialities : mixed|string|int

array of specialities - will be displayed on the admin download as "footnote"

Type

mixed|string|int — specialities

$supportedEapMethods

$supportedEapMethods : mixed|string|int

list of supported EAP methods

Type

mixed|string|int — EAP methods

$nomenclature_fed

$nomenclature_fed : 

the custom displayable variant of the term 'federation'

Type

$nomenclature_inst

$nomenclature_inst : 

the custom displayable variant of the term 'institution'

Type

$attributes

$attributes : mixed|string|int

Array passing all options to the device module.

$attrbutes array contains option values defined for the institution and a particular profile (possibly overriding one another) ready for the device module to consume.

For each of the options the value is another array of vales (even if only one value is present). Some attributes may be missing if they have not been configured for a viven institution or profile.

The following attributes are meant to be used by device modules:

  • general:geo_coordinates - geographical coordinates of the institution or a campus
  • support:info_file - consent file displayed to the users
  • general:logo_file - file data containing institution logo
  • support:eap_types - URL to a local support page for a specific eap methiod, not to be confused with general:url
  • support:email - email for users to contact for local instructions
  • support:phone - telephone number for users to contact for local instructions
  • support:url - URL where the user will find local instructions
  • internal:info_file - the pathname of the info_file saved in the working directory
  • internal:logo_file - array of pathnames of logo_files saved in the working directory
  • internal:CAs - the value is an array produced by X509::processCertificate() with the following filds
  • internal:SSID - an array indexed by SSID strings with values either TKIP or AES; if TKIP is set the both WPA/TKIP and WPA2/AES should be set if AES is set the this is a WPA2/AES only SSID; the consortium's defined SSIDs are always set as the first array elements.
  • internal:consortia an array of consortion IO as declared in the config-confassistant
  • internal:profile_count - the number of profiles for the associated IdP

these attributes are available and can be used, but the "internal" attributes are better suited for modules

  • eap:ca_file - certificate of the CA signing the RADIUS server key
  • media:SSID - additional SSID to configure, WPA2/AES only (device modules should use internal:SSID)
  • media:SSID_with_legacy - additional SSID to configure, WPA2/AES and WPA/TKIP (device modules should use internal:SSID)

Type

mixed|string|int —

$module_path

$module_path : 

stores the path to the module source location and is used by copyFile and translateFile the only reason for it to be a public variable ies that it is set by the DeviceFactory class module_path should not be used by module drivers.

Type

$selectedEap

$selectedEap : mixed|string|int

* The optimal EAP type selected given profile and device

Type

mixed|string|int —

$selectedEapObject

$selectedEapObject : 

Type

$sign

$sign : 

the path to the profile signing program device modules which require signing should use this property to exec the signer the signer program must accept two arguments - input and output file names the signer program mus operate in the local directory and filenames are relative to this directory

Type

$signer

$signer : 

Type

$device_id

$device_id : 

The string identifier of the device (don't show this to users)

Type

$options

$options : mixed|string|int

See devices-template.php for a list of available options

Type

mixed|string|int —

$support_email_substitute

$support_email_substitute : 

This string will be shown if no support email was configured by the admin

Type

$support_url_substitute

$support_url_substitute : 

This string will be shown if no support URL was configured by the admin

Type

$installerBasename

$installerBasename : 

This string should be used by all installer modules to set the installer file basename.

Type

$deviceUUID

$deviceUUID : 

stores identifier used by GEANTLink profiles

Type

Methods

__construct()

__construct() : 

Constructs a Device object.

It is CRUCIAL that the constructor sets $this->supportedEapMethods to an array of methods available for the particular device.

Returns

setup()

setup(\core\AbstractProfile  profile,  token = NULL,  importPassword = NULL) : 

Set up working environment for a device module

Sets up the device module environment taking into account the actual profile selected by the user in the GUI. The selected profile is passed as the Profile $profile argumant.

This method needs to be called after the device instance has been created (the GUI class does that)

setup performs the following tasks:

  • collect profile attributes and pass them as the attributes property;
  • create the temporary working directory
  • process CA certificates and store them as 'internal:CAs' attribute
  • process and save optional info files and store references to them in 'internal:info_file' attribute

Parameters

\core\AbstractProfile profile

the profile object which will be passed by the caller

token
importPassword

Returns

calculatePreferredEapType()

calculatePreferredEapType(mixed|string|int  eapArrayofObjects) : 

Selects the preferred eap method based on profile EAP configuration and device EAP capabilities

Parameters

mixed|string|int eapArrayofObjects

an array of eap methods supported by a given device

Returns

writeDeviceInfo()

writeDeviceInfo() : 

prepare module desctiption and usage information

Returns

HTML text to be displayed in the information window

getAttibute()

getAttibute( attrName) : 

Parameters

attrName

Returns

writeInstaller()

writeInstaller() : 

prepare a zip archive containing files and settings which normally would be used inside the module to produce an installer

Returns

installer path name

__destruct()

__destruct() : 

destroys the entity.

Logs the end of lifetime of the entity to the debug log on level 5.

Returns

getAttributeValue()

getAttributeValue(mixed|string|int  attributeArray, string|int  index1, string|int  index2) : 

This is a helper fuction to retrieve a value from two-dimensional arrays The function tests if the value for the first indes is defined and then the same with the second and finally returns the value if something on the way is not defined, NULL is returned

Parameters

mixed|string|int attributeArray
string|int index1
string|int index2

Returns

createTemporaryDirectory()

createTemporaryDirectory(  purpose = installer,   failIsFatal = 1) : mixed|string|int

create a temporary directory and return the location

Parameters

purpose

one of 'installer', 'logo', 'test' defined the purpose of the directory

failIsFatal

decides if a creation failure should cause an error; defaults to true

Returns

mixed|string|int —

the tuple of: base path, absolute path for directory, directory name

rrmdir()

rrmdir(  dir) : 

this direcory delete function has been copied from PHP documentation

Parameters

dir

name of the directory to delete

Returns

uuid()

uuid(  prefix,  deterministicSource = NULL) : 

generates a UUID, for the devices which identify file contents by UUID

Parameters

prefix

an extra prefix to set before the UUID

deterministicSource

Returns

UUID (possibly prefixed)

randomString()

randomString(  length,   keyspace = 23456789abcdefghijkmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ) : 

produces a random string

Parameters

length

the length of the string to produce

keyspace

the pool of characters to use for producing the string

Throws

\Exception

Returns