The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Config-Apple-Profile-v0.87.1-TRIAL
River stage zero No dependents
++
/ Config::Apple::Profile::Payload::Common

NAME

Config::Apple::Profile::Payload::Common - Base class for almost all payload types, with common payload keys.

DESCRIPTION

This module serves two purposes.

First, this module contains code to store payload data, to validate client-provided data, and to export payload data as a plist.

Second, this module defines the payload keys that are common to almost all payload types. Specific payload types (classes) will include these common payload types in their own payload type-specific list.

Ideally, each payload type will be implemented as a class that subclasses this one, using this class to do all of the work, leaving the subclass to define the payload keys specific to that subclass.

CLASS METHODS

new()

Returns a new object.

INSTANCE METHODS

keys()

Returns a hashref that contains the list of payload keys recognized by this instance.

NOTE: The hashref points to a hash that is read-only. Any attempts to modify will cause your code to die. You probably want to look at payload().

payload()

Returns a hashref that can be used to access the contents of the payload. This is a reference to a tied hash, so you can not use it as liberally as a normal hash. The only keys that will be accepted are those listed under "PAYLOAD KEYS".

The following exception may be thrown when accessing a hash key:

Config::Apple::Profile::Payload::Common::KeyInvalid

Thrown when attempting to access a payload key that is not valid for this payload.

If a payload key is valid, but has not been set, then undef is returned.

The following exceptions may be thrown when setting a hash key:

Config::Apple::Profile::Payload::Common::KeyInvalid

Thrown when attempting to access a payload key that is not valid for this payload.

Config::Apple::Profile::Payload::Common::ValueInvalid

Thrown when attempting to set an invalid value for this payload key.

You can use exists to test if a particular key is valid for this payload, and you can use defined to test if a particular key actually has a value defined. Take note that calling defined with an invalid key name will always return false.

You can use delete to delete a key.

plist([option1_name => option1_value, ...])

Return a copy of this payload, represented as a Mac::Propertylist object. All strings will be in UTF-8, and all Data entries will be Base64-encoded. This method is used when assembling payloads into a profile.

There are two ways to get string output from the plist object:

    # First, get your plist object from the payload
    my $plist = $payload->plist();
    
    # If you just want the <dict> XML element and its contents, do this...
    my $dict_element = $plist->write;
    
    # If you want the complete XML plist, with headers, do this...
    use Mac::PropertyList;
    my $complete_plist = Mac::PropertyList::plist_as_string($plist);

Several parameters can be provided, which will influence how this method runs.

target

If target (a value from Config::Apple::Profile::Targets) is provided, then this will be taken into account when exporting. Only payload keys that are used on the specified target will be included in the output.

The completeness option controls what happens if keys are excluded.

version

If version (a version string) is provided, then only payload keys that work on the specified version will be included in the output.

If version is provided, then target must also be set, but target can be set without setting version.

The completeness option controls what happens if keys are excluded.

completeness

If completeness is set to a true value, and keys are excluded because of target or version, then plist will throw an exception. If set to a false value, or if not set at all, then no exceptions will be thrown, and a less-than-complete (but still valid) plist will be returned.

The following exceptions may be thrown:

Config::Apple::Profile::Exception::KeyRequired

Thrown if a required key has not been set.

Config::Apple::Profile::Exception::Incomplete

Thrown if payload keys are being excluded from the output because of target or version.

populate_id()

Populates the PayloadIdentifier and PayloadUUID fields, if they are not already set. In addition, if the payload has any keys of type $PayloadClass, then populate_id will also be called on them.

Sub-classes may decide to override this, so as to add extra functionality.

exportable([target])

Returns true if the payload is complete enough to be exported. In other words, all required keys must have values provided.

exportable() will return false if all UUID and Identifier fields are not filled in, so it is suggested that you call populate_id() before calling exportable().

validate_key($key, $value)

Confirm the value provided is valid for the given payload key, and return a de-tained copy of $value, or undef if the provided value is invalid.

$key is the name of the payload key being set, and $value is the proposed new value. This class will perform checking for all payload types except for Data payloads. The checks performed will be very basic.

Subclasses should override this method to check their keys, and then call SUPER::validate_key($self, $key, $value) to check the remaining keys.

The following exceptions may be thrown:

Config::Apple::Profile::Payload::Common::KeyUnknown

Thrown if the payload key referenced is unknown.

NOTE: An exception will not be thrown if the value is found to be invalid. This is intentional!

NOTE: To test the result of this method, you should use defined, because it's possible for a valid value to be false (for example, 0)!

PAYLOAD KEYS

Every payload type has a certain number of common keys. Those common keys are defined (not stored) in %payloadKeys.

For general information on payload types, see Config::Apple::Profile::Payload::Types.

PayloadIdentifier

A Identifier for this specific payload. It must be unique.

PayloadUUID

A UUID for this specific payload. It must be unique.

PayloadDisplayName

Optional

A String that the user will be able to see when looking at the details of the profile that is about to be installed.

PayloadDescription

Optional

A String that the user will be able to see when looking at the details of the profile that is about to be installed.

PayloadOrganization

Optional

A String that the user will be able to see when looking at the details of the profile that is about to be installed.

PayloadType

A Identifier that identifies which type of payload this is. This value may not be set by the client. Instead, the value is automatically determined based on which Config::Apple::Profile::Payload::Types:: class is being used.

PayloadVersion

A Number that identifies the version of the payload type. This specifies the version of the standard, not the client's own revision number. Right now, all payload types have a version number of 1.

DEVELOPER NOTES

The following sections have information that will be useful to people working on the code that makes up this release.

%payloadKeys contents

The %payloadKeys hash is critical, so it is important to know how it is constructed. To start, each key in the hash is a key that appears in a payload. The value corresponding to the key is a hashref, which can contain the following keys:

type

This key's value is a value from Config::Apple::Profile::Payload::Types. It is used to specify the type of data the profile key contains.

The type is used when creating Mac::PropertyList objects, and when doing value-checking.

If a payload class uses <$ProfileClass> as a type, then the payload class is responsible for providing an instance method named construct, which takes the payload key name as its only parameter, and returns a new object.

This key must be present.

subtype

This key is required when type is set to $ProfileDict or $ProfileArray.

If type is set to $ProfileDict, then subtype contains the type of data stored as values. That data type will be used for validation, when entries are added to the Perl hash representing the dictionary.

If type is set to $ProfileArray, then subtype contains the type of data stored in the array. That data type will be used for validation, when entries are added to the Perl array.

If a payload class uses <$ProfileClass> as a subtype, then the payload class is responsible for providing an instance method named construct, which takes the payload key name as its only parameter, and returns a new object.

For other values of the type key, this key must not be present.

description

This key's value contains a human-readable description of the profile key. The purpose of this is so that client software can easily enumerate profile keys, such as when making a web application.

This key must be present.

targets

This key's value is a hashref. Within the hashref, the keys are platform identifiers, scalars taken from Config::Apple::Profile::Targets. The value for each key is a version object representing the earliest version of the named platform's OS which supports this payload key.

If a platform does not support a particular key at all, that platform should not be included in the hashref.

This key must be present, and the hashref must contain at least one entry.

optional

If this key is present, then this payload key does not have to be present. This might mean that a key is completely optional (like PayloadDescription), or it might mean that the value will be auto-generated (like PayloadUUID).

It doesn't matter what this key is set to, its presence is what's important.

Optional checks are done when exportable is run, at the very least.

unique

If this key is present, then this payload key's value needs to be unique across all payloads in the profile. This is normally used for things like the UUID and the payload identifier, which need to be unique.

It doesn't matter what this key is set to, its presence is what's important.

Uniqueness checks are done during profile creation time only.

private

If this key is present, then this payload key's value is something that should only be transmitted when the profile is encrypted. This is meant for things like passwords, which should not be sent in the clear.

Right now, none of the code in this release does anything with this key. It is provided solely for future use.

value

If this key is present, then the corresponding value will be used as the value for the payload key. Any attempts by the user to change the payload key's value will throw an exception.

This is used for things like PayloadVersion and PayloadType, which are fixed.

ACKNOWLEDGEMENTS

Refer to the Config::Apple::Profile for acknowledgements.

AUTHOR

A. Karl Kornel, <karl at kornel.us>

COPYRIGHT AND LICENSE

Copyright © 2014 A. Karl Kornel.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.