1WWW::Google::Contacts::UCsoenrtaCcotn(t3r)ibuted Perl DoWcWuWm:e:nGtoaotgiloen::Contacts::Contact(3)
2
3
4
6 use WWW::Google::Contacts;
7
8 my $google = WWW::Google::Contacts->new( username => "your.username", password => "your.password" );
9
10 my $contact = $google->new_contact;
11 $contact->full_name("Emmett Brown");
12
13 A lot of fields, such as email, phone number and so on, are accessible
14 as array refs.
15
16 foreach my $email (@{ $contact->email }) {
17 print "He got email address: " . $email->value . "\n";
18 }
19
20 When you have made changes to your contact, you need to save them back
21 to Google. This is done either by a create call (for new contacts) or
22 an update call (for existing contacts).
23
24 $contact->create;
25
26 Alternatively, you can use the create_or_update method, which will do
27 the right thing.
28
29 $contact->create_or_update;
30
32 $contact->create
33 Writes the contact to your Google account.
34
35 $contact->retrieve
36 Fetches contact details from Google account.
37
38 $contact->update
39 Updates existing contact in your Google account.
40
41 $contact->delete
42 Deletes contact from your Google account.
43
44 $contact->create_or_update
45 Creates or updates contact, depending on if it already exists.
46
48 All these attributes are gettable and settable on Contact objects.
49
50 given_name
51 $contact->given_name("Arnold");
52
53 additional_name
54 $contact->additional_name("J");
55
56 family_name
57 $contact->family_name("Rimmer");
58
59 name_prefix
60 $contact->name_prefix("Mrs");
61
62 name_suffix
63 $contact->name_suffix("III");
64
65 full_name
66 If this is set to what seems like "$given_name $family_name", those
67 attributes will be automatically set.
68
69 email
70 $contact->email is, if defined, an array reference with 1 or more Email
71 objects. The Email objects have the following accessors;
72
73 type
74 This is an object in itself, which has 2 accessors; name and uri.
75
76 label
77 If you don't want to use the predefined types (defined by Google)
78 you can set this label instead.
79
80 value
81 The email address.
82
83 display_name
84 An optional display name.
85
86 primary
87 A boolean stating whether this is the primary email address.
88
89 Example code (set the first work email as the primary address):
90
91 foreach my $email (@{ $contact->email }) {
92 if ( $email->type->name eq 'work' ) {
93 $email->primary(1);
94 last;
95 }
96 }
97
98 Explicitly setting all email details:
99
100 $contact->email({
101 type => "work",
102 value => 'shenanigans@example.com',
103 display_name => 'Shenanigans',
104 primary => 1,
105 });
106
107 Note that this will overwrite any previous email addresses for the
108 contact. To add rather than replace, see add_email below.
109
110 If you're just setting the email value, type will default to "work" and
111 leave other fields empty.
112
113 $contact->email( 'smeghead@reddwarf.net' );
114
115 To specify several email addresses, you could either;
116
117 • provide them all in an array
118
119 $contact->email([
120 { type => "work", value => 'underpaid@bigcompany.com' },
121 { type => "home", value => 'angryblogger@someblogsite.com' },
122 ]);
123
124 • call add_email
125
126 $contact->add_email( 'homer@simpson.name' );
127
128 phone_number
129 $contact->phone_number is, if defined, an array reference with 1 or
130 more PhoneNumber objects. The PhoneNumber objects have the following
131 accessors;
132
133 type
134 This is an object in itself, which has 2 accessors; name and uri.
135
136 label
137 If you don't want to use the predefined types (defined by Google)
138 you can set this label instead.
139
140 value
141 The phone number
142
143 Explicitly setting all phone details:
144
145 $contact->phone_number({
146 type => "mobile",
147 value => "+449812323",
148 });
149
150 Just setting the value will set type to default value "mobile".
151
152 $contact->phone_number( "+1666666" );
153
154 To specify several phone numbers, you could either;
155
156 • provide them all in an array
157
158 $contact->phone_number([
159 { type => "mobile", value => "12345" },
160 { type => "home", value => "666" },
161 ]);
162
163 • call add_phone_number
164
165 $contact->add_phone_number({
166 type => "home",
167 value => "02078712345"
168 });
169
170 im (Instant Messaging)
171 $contact->im is, if defined, an array reference with 1 or more IM
172 objects. The IM objects have the following accessors;
173
174 type
175 This is an object in itself, which has 2 accessors; name and uri.
176
177 label
178 If you don't want to use the predefined types (defined by Google)
179 you can set this label instead.
180
181 protocol
182 This is an object in itself, which has 2 accessors; name and uri.
183
184 Which protocol is used for this IM address. Possible name values
185 include AIM, MSN, YAHOO. SKYPE, QQ, GOOGLE_TALK, ICQ, JABBER.
186
187 value
188 Email address for the IM account.
189
190 You can specify all IM details:
191
192 $contact->im({
193 type => "home",
194 protocol => "MSN",
195 value => 'some.email@example.com',
196 });
197
198 Or you can just choose to give the IM address:
199
200 $contact->im( 'some.email@example.com' );
201
202 organization
203 $contact->organization is, if defined, an array reference with 1 or
204 more Organization objects. The Organization objects have the following
205 accessors;
206
207 type
208 This is an object in itself, which has 2 accessors; name and uri.
209
210 label
211 If you don't want to use the predefined types (defined by Google)
212 you can set this label instead.
213
214 department
215 Specifies a department within the organization.
216
217 job_description
218 Description of a job within the organization.
219
220 name
221 The name of the organization.
222
223 symbol
224 Symbol of the organization.
225
226 title
227 The title of a person within the organization.
228
229 primary
230 Boolean. When multiple organizations extensions appear in a contact
231 kind, indicates which is primary. At most one organization may be
232 primary.
233
234 where
235 A place associated with the organization, e.g. office location.
236
237 postal_address
238 $contact->postal_address is, if defined, an array reference with 1 or
239 more PostalAddress objects. The PostalAddress objects have the
240 following accessors;
241
242 type
243 This is an object in itself, which has 2 accessors; name and uri.
244
245 label
246 If you don't want to use the predefined types (defined by Google)
247 you can set this label instead.
248
249 mail_class
250 This is an object in itself, which has 2 accessors; name and uri.
251
252 Classes of mail accepted at the address. Possible name values are
253 both, letters, parcels and neither. Unless specified both is
254 assumed.
255
256 usage
257 This is an object in itself, which has 2 accessors; name and uri
258
259 The context in which this addess can be used. Possible values are
260 general and local. Local addresses may differ in layout from
261 general addresses, and frequently use local script (as opposed to
262 Latin script) as well, though local script is allowed in general
263 addresses. Unless specified general usage is assumed.
264
265 primary
266 Boolean. Specifies the address as primary.
267
268 agent
269 The agent who actually receives the mail. Used in work addresses.
270 Also for 'in care of' or 'c/o'.
271
272 house_name
273 Used in places where houses or buildings have names (and not
274 necessarily numbers), eg. "The Pillars".
275
276 street
277 Can be street, avenue, road, etc. This element also includes the
278 house number and room/apartment/flat/floor number.
279
280 pobox
281 Covers actual P.O. boxes, drawers, locked bags, etc. This is
282 usually but not always mutually exclusive with street.
283
284 neighborhood
285 This is used to disambiguate a street address when a city contains
286 more than one street with the same name, or to specify a small
287 place whose mail is routed through a larger postal town. In China
288 it could be a county or a minor city.
289
290 city
291 Can be city, village, town, borough, etc. This is the postal town
292 and not necessarily the place of residence or place of business.
293
294 subregion
295 Handles administrative districts such as U.S. or U.K. counties that
296 are not used for mail addressing purposes. Subregion is not
297 intended for delivery addresses.
298
299 region
300 A state, province, county (in Ireland), Land (in Germany),
301 departement (in France), etc.
302
303 postcode
304 Postal code. Usually country-wide, but sometimes specific to the
305 city (e.g. "2" in "Dublin 2, Ireland" addresses).
306
307 country
308 An object with two accessors; name and code.
309
310 formatted
311 The full, unstructured postal address.
312
313 billing_information
314 Specifies billing information of the entity represented by the contact.
315
316 notes
317 Arbitrary notes about your friend.
318
319 $contact->notes( "He's a lumberjack, but he's ok" );
320
321 birthday
322 If defined, returns an object with one accessor;
323
324 when
325 Birthday date, given in format YYYY-MM-DD (with the year), or
326 --MM-DD (without the year).
327
328 ...tba
329 Sorry, haven't documented all attributes yet :(
330
332 Contacts can belong to 0 or more groups. This section describes how to
333 get and set group memberships.
334
335 $contact->groups
336 Returns an array reference of all groups, as
337 WWW::Google::Contacts::Group objects.
338
339 $contact->add_group_membership( group )
340 The group argument can either be:
341
342 An WWW::Google::Contacts::Group object
343 The ID of a group, as a URL
344 The name of a group
345
346 Do note that the group has to exist on the Google servers before you
347 can add this membership.
348
350 Magnus Erixzon <magnus@erixzon.com>
351
353 This software is copyright (c) 2010 by Magnus Erixzon.
354
355 This is free software; you can redistribute it and/or modify it under
356 the same terms as perl itself.
357
358
359
360perl v5.32.1 2021-01-27 WWW::Google::Contacts::Contact(3)