1WWW::Google::Contacts::UCsoenrtaCcotn(t3r)ibuted Perl DoWcWuWm:e:nGtoaotgiloen::Contacts::Contact(3)
2
6 use WWW::Google::Contacts;
7 my $google = WWW::Google::Contacts->new( username => "your.username", password => "your.password" );
9 my $contact = $google->new_contact;
11 $contact->full_name("Emmett Brown");
12 A lot of fields, such as email, phone number and so on, are accessible
14 as array refs.
15 foreach my $email (@{ $contact->email }) {
17 print "He got email address: " . $email->value . "\n";
18 }
19 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 $contact->create;
25 Alternatively, you can use the create_or_update method, which will do
27 the right thing.
28 $contact->create_or_update;
30
32 $contact->create
33 Writes the contact to your Google account.
34 $contact->retrieve
36 Fetches contact details from Google account.
37 $contact->update
39 Updates existing contact in your Google account.
40 $contact->delete
42 Deletes contact from your Google account.
43 $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 given_name
51 $contact->given_name("Arnold");
52 additional_name
54 $contact->additional_name("J");
55 family_name
57 $contact->family_name("Rimmer");
58 name_prefix
60 $contact->name_prefix("Mrs");
61 name_suffix
63 $contact->name_suffix("III");
64 full_name
66 If this is set to what seems like "$given_name $family_name", those
67 attributes will be automatically set.
68 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 type
74 This is an object in itself, which has 2 accessors; name and uri.
75 label
77 If you don't want to use the predefined types (defined by Google)
78 you can set this label instead.
79 value
81 The email address.
82 display_name
84 An optional display name.
85 primary
87 A boolean stating whether this is the primary email address.
88 Example code (set the first work email as the primary address):
90 foreach my $email (@{ $contact->email }) {
92 if ( $email->type->name eq 'work' ) {
93 $email->primary(1);
94 last;
95 }
96 }
97 Explicitly setting all email details:
99 $contact->email({
101 type => "work",
102 value => 'shenanigans@example.com',
103 display_name => 'Shenanigans',
104 primary => 1,
105 });
106 Note that this will overwrite any previous email addresses for the
108 contact. To add rather than replace, see add_email below.
109 If you're just setting the email value, type will default to "work" and
111 leave other fields empty.
112 $contact->email( 'smeghead@reddwarf.net' );
114 To specify several email addresses, you could either;
116 • provide them all in an array
118 $contact->email([
120 { type => "work", value => 'underpaid@bigcompany.com' },
121 { type => "home", value => 'angryblogger@someblogsite.com' },
122 ]);
123 • call add_email
125 $contact->add_email( 'homer@simpson.name' );
127 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 type
134 This is an object in itself, which has 2 accessors; name and uri.
135 label
137 If you don't want to use the predefined types (defined by Google)
138 you can set this label instead.
139 value
141 The phone number
142 Explicitly setting all phone details:
144 $contact->phone_number({
146 type => "mobile",
147 value => "+449812323",
148 });
149 Just setting the value will set type to default value "mobile".
151 $contact->phone_number( "+1666666" );
153 To specify several phone numbers, you could either;
155 • provide them all in an array
157 $contact->phone_number([
159 { type => "mobile", value => "12345" },
160 { type => "home", value => "666" },
161 ]);
162 • call add_phone_number
164 $contact->add_phone_number({
166 type => "home",
167 value => "02078712345"
168 });
169 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 type
175 This is an object in itself, which has 2 accessors; name and uri.
176 label
178 If you don't want to use the predefined types (defined by Google)
179 you can set this label instead.
180 protocol
182 This is an object in itself, which has 2 accessors; name and uri.
183 Which protocol is used for this IM address. Possible name values
185 include AIM, MSN, YAHOO. SKYPE, QQ, GOOGLE_TALK, ICQ, JABBER.
186 value
188 Email address for the IM account.
189 You can specify all IM details:
191 $contact->im({
193 type => "home",
194 protocol => "MSN",
195 value => 'some.email@example.com',
196 });
197 Or you can just choose to give the IM address:
199 $contact->im( 'some.email@example.com' );
201 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 type
208 This is an object in itself, which has 2 accessors; name and uri.
209 label
211 If you don't want to use the predefined types (defined by Google)
212 you can set this label instead.
213 department
215 Specifies a department within the organization.
216 job_description
218 Description of a job within the organization.
219 name
221 The name of the organization.
222 symbol
224 Symbol of the organization.
225 title
227 The title of a person within the organization.
228 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 where
235 A place associated with the organization, e.g. office location.
236 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 type
243 This is an object in itself, which has 2 accessors; name and uri.
244 label
246 If you don't want to use the predefined types (defined by Google)
247 you can set this label instead.
248 mail_class
250 This is an object in itself, which has 2 accessors; name and uri.
251 Classes of mail accepted at the address. Possible name values are
253 both, letters, parcels and neither. Unless specified both is
254 assumed.
255 usage
257 This is an object in itself, which has 2 accessors; name and uri
258 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 primary
266 Boolean. Specifies the address as primary.
267 agent
269 The agent who actually receives the mail. Used in work addresses.
270 Also for 'in care of' or 'c/o'.
271 house_name
273 Used in places where houses or buildings have names (and not
274 necessarily numbers), eg. "The Pillars".
275 street
277 Can be street, avenue, road, etc. This element also includes the
278 house number and room/apartment/flat/floor number.
279 pobox
281 Covers actual P.O. boxes, drawers, locked bags, etc. This is
282 usually but not always mutually exclusive with street.
283 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 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 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 region
300 A state, province, county (in Ireland), Land (in Germany),
301 departement (in France), etc.
302 postcode
304 Postal code. Usually country-wide, but sometimes specific to the
305 city (e.g. "2" in "Dublin 2, Ireland" addresses).
306 country
308 An object with two accessors; name and code.
309 formatted
311 The full, unstructured postal address.
312 billing_information
314 Specifies billing information of the entity represented by the contact.
315 notes
317 Arbitrary notes about your friend.
318 $contact->notes( "He's a lumberjack, but he's ok" );
320 birthday
322 If defined, returns an object with one accessor;
323 when
325 Birthday date, given in format YYYY-MM-DD (with the year), or
326 --MM-DD (without the year).
327 ...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 $contact->groups
336 Returns an array reference of all groups, as
337 WWW::Google::Contacts::Group objects.
338 $contact->add_group_membership( group )
340 The group argument can either be:
341 An WWW::Google::Contacts::Group object
343 The ID of a group, as a URL
344 The name of a group
345 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 This is free software; you can redistribute it and/or modify it under
356 the same terms as perl itself.
357perl v5.38.0 2023-07-21 WWW::Google::Contacts::Contact(3)