File Coverage

blib/lib/Config/Apple/Profile/Payload/Types.pm
Criterion Covered Total %
statement 15 15 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod n/a
total 20 20 100.0


line stmt bran cond sub pod time code
1             package Config::Apple::Profile::Payload::Types;
2              
3 15     15   126 use 5.10.1;
  15         37  
  15         571  
4 15     15   68 use strict;
  15         207  
  15         556  
5 15     15   65 use warnings FATAL => 'all';
  15         23  
  15         1139  
6              
7             our $VERSION = '0.87.1';
8              
9             use Exporter::Easy (
10 15         118 OK => [qw(
11             $ProfileString $ProfileNumber $ProfileData $ProfileBool
12             $ProfileReal $ProfileDate $ProfileDict $ProfileArray
13             $ProfileNSDataBlob $ProfileUUID $ProfileIdentifier
14             )],
15             TAGS => [
16             'all' => [qw(
17             $ProfileString $ProfileNumber $ProfileData $ProfileBool
18             $ProfileReal $ProfileDate $ProfileDict $ProfileArray
19             $ProfileNSDataBlob $ProfileUUID $ProfileIdentifier $ProfileClass
20             )],
21             ],
22 15     15   6656 );
  15         17393  
23 15     15   4924 use Readonly;
  15         24  
  15         3375  
24              
25              
26             =encoding utf8
27              
28             =head1 NAME
29              
30             Config::Apple::Profile::Payload::Types - Data types for payload keys.
31              
32             =head1 DESCRIPTION
33              
34             Apple Configuration Profiles contain one or more I. Each payload
35             contains a dictionary, which can be thought of like a Perl hash. Within a
36             payload's dictionary, each key's value is restricted to a specific type.
37             One key might require a number; a different key might require a string, or some
38             binary data.
39              
40             Provided in this module are a number of Readonly scalars that will be used
41             (instead of strings) to identify the data types for configuration profile keys.
42             The scalars are all OK for import into your local namespace, or you can simply
43             import C<:all> to get all of them at once.
44              
45             =head1 TYPES
46              
47             Apple Configuration Profile payloads use the following types:
48              
49             =head2 String (C<$ProfileString>)
50              
51             A UTF-8 string. The client should simply provide a Perl string (NOT a binary
52             string). Multi-line strings are allowed, although specific payload keys may
53             not allow this. Empty strings are B allowed.
54              
55             B If your source data was not ASCII, and not UTF-8, then please make
56             sure you have converted it before doing anything else! "converted it" normally
57             means using C to convert from the original encoding. Your
58             string will not be valid unless it can be encoded as UTF-8.
59              
60             =cut
61              
62             Readonly our $ProfileString => 1;
63              
64              
65             =head2 Number (C<$ProfileNumber>)
66              
67             An Integer, which may be positive, zero, or negative. The plist standard
68             doesn't specify a range, but one may be imposed by specific keys.
69              
70             =cut
71              
72             Readonly our $ProfileNumber => 2;
73              
74              
75             =head2 Real (C<$ProfileReal>)
76              
77             A real number, which may be positive, zero, or negative. It may also have
78             an exponent. The plist standard doesn't specify a range, but one may be
79             imposed by specific keys.
80              
81             =cut
82              
83             Readonly our $ProfileReal => 5;
84              
85              
86             =head2 Data (C<$ProfileData>)
87              
88             Binary data.
89              
90             Binary data may be provided by the client in multiple ways.
91             Clients can provide an open filehandle, or an open C object.
92             C is used to make sure the handle/object is open.
93              
94             The file needs to be open for reading.
95              
96             The client may also provide a string. If a string is provided, then it must be
97             a I, I string. In other words, C needs to
98             return C. If the flag is C, then you probably need to use
99             C (or maybe C) to get a binary string.
100              
101             When reading a Data key, the client will always get a plain filehandle back.
102              
103             =cut
104              
105             Readonly our $ProfileData => 3;
106              
107              
108             =head2 Boolean (C<$ProfileBool>)
109              
110             Either True for False. When reading a boolean from a payload's contents, a 1
111             is used to represent true, and 0 is returned for false. When setting a boolean,
112             the value provided is filtered using the code C<($value) ? 1 : 0>. As long as
113             you aren't providing C as the input, your input will probably be
114             accepted!
115              
116             =cut
117              
118             Readonly our $ProfileBool => 4;
119              
120              
121             =head2 Date (C<$ProfileDate>)
122              
123             A date. This is stored internally as a C object, and when read a
124             C object will be returned. When serialized into plist form, the
125             time will be in UTC, but no other guarantees are made about the timezone when
126             the object is stored internally, so if you read a Date, be sure to call
127             C<< ->set_time_zone() >> before outputting it yourself.
128              
129             If a string is provided, L will be used to parse it.
130             For best results, parse it yourself, and provide the resulting C
131             object!
132              
133             =cut
134              
135             Readonly our $ProfileDate => 6;
136              
137              
138             =head2 Dictionary (C<$ProfileDict>)
139              
140             A dictionary is the plist equivalent to a Perl hash, and that is what will be
141             made available. The client should expect the hash to restrict what key names,
142             and what values, are accepted. For more information, see the
143             documentation for the specific payload key.
144              
145             =cut
146              
147             Readonly our $ProfileDict => 10;
148              
149              
150             =head2 Array (C<$ProfileArray>)
151              
152             An array, similar to a Perl array. The client should expect the array to only
153             accept certain data types. For more information, see the documentation for the
154             specific payload key.
155              
156             =cut
157              
158             Readonly our $ProfileArray => 11;
159              
160              
161             =head2 NSData Blob
162              
163             This is a weird type. The only place it appears in the I
164             Reference> (the edition dated 2014-03-20) is in the C key in the
165             Exchange payload. I don't really understand this, though I'm guessing it's
166             really a Data type, and the I is referring to the contents.
167              
168             Until I get more information on what exactly this is, this type will likely go
169             unimplemnented. Right now, the same checks are performed as for the
170             C type.
171              
172             =cut
173              
174             Readonly our $ProfileNSDataBlob => 20;
175              
176              
177             =head1 CUSTOM TYPES
178              
179             The following types are not defined in the plist standard, but they are being
180             treated specially here.
181              
182             =head2 UUID (C<$ProfileUUID>)
183              
184             I
185              
186             Although the plist format does not have a special type for UUIDs (a simple
187             String is used), these modules designate a special type for UUIDs as a
188             convenience to the client. All payloads have a UUID as one of the required
189             keys. If the client does not specify a UUID when creating a payload, then
190             one will be lazily auto-generated.
191              
192             If you would like to set an explicit UUID, you may provide a C
193             object, a C object, or a string that C can parse. When
194             reading, a C object is returned, but that can be converted into a
195             string very easily:
196              
197             $uuid = "$uuid";
198              
199             =cut
200              
201             Readonly our $ProfileUUID => 21;
202              
203              
204             =head2 Identifier (C<$ProfileIdentifier>)
205              
206             This is another convenience type. All payloads require an identifier,
207             which is a reverse-DNS-style (Java-style) string. If the client does not
208             specify an identifier, then one will be lazily auto-generated.
209              
210             See RFC 1035 for the standard relating to host and domain names, but please note
211             that spaces are I acceptable here, even though they may be in RFC 1035.
212              
213             =cut
214              
215             Readonly our $ProfileIdentifier => 22;
216              
217              
218             =head2 Class (C<$ProfileClass>)
219              
220             This profile type is used to indicate that the value is an instance of a class.
221             The class is a sub-class of C, so the
222             methods implemented in that class are all available. More information about
223             what specific sub-class is used can be found in the documentation for the
224             specific payload key.
225              
226             =cut
227              
228             Readonly our $ProfileClass => 24;
229              
230              
231             =head1 SEE ALSO
232              
233             L, L, L, L, L,
234             L,
235             L
236              
237             =head1 ACKNOWLEDGEMENTS
238              
239             Refer to L for acknowledgements.
240              
241             =head1 AUTHOR
242              
243             A. Karl Kornel, C<< >>
244              
245             =head1 COPYRIGHT AND LICENSE
246              
247             Copyright © 2014 A. Karl Kornel.
248              
249             This program is free software; you can redistribute it and/or modify it
250             under the terms of either: the GNU General Public License as published
251             by the Free Software Foundation; or the Artistic License.
252              
253             See L for more information.
254              
255             =cut
256              
257             1;