Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::Google::Calendar(User Contributed Perl DocumentatNet::Google::Calendar(3)

NAME
       Net::Google::Calendar - programmatic access to Google's Calendar	API

SYNOPSIS
	   # this will only get	you a read only	feed
	   my $cal = Net::Google::Calendar->new( url =>	$private_url );

       or

	   # this will get you a read-write feed.
	   my $cal = Net::Google::Calendar->new;
	   $cal->login($username, $password);

       or

	   # this will also get	you a read-write feed
	   my $cal = Net::Google::Calendar->new;
	   $cal->auth($username, $auth_token);

       or
	   # this will again get you a read-write feed
	   my $cal = Net::Google::Calendar->new;
	   $cal->oauth(Net::Google::OAuth);

       or you can pass in a url	to specify a particular	calendar

	   my $cal = Net::Google::Calendar->new( url =>	$non_default_url );
	   $cal->login($username, $password);
	   # or	$cal->auth($username, $auth_token) obviously

       then

	   for ($cal->get_events()) {
	       print $_->title."\n";
	       print $_->content->body."\n*****\n\n";
	   }

	   my $c;
	   for ($cal->get_calendars) {
	       print $_->title."\n";
	       print $_->id."\n\n";
	       $c = $_ if ($_->title eq	'My Non	Default	Calendar');
	   }
	   $cal->set_calendar($c);
	   print $cal->id." has	".scalar($cal->get_events)." events\n";

	   # everything	below here requires a read-write feed
	   my $entry = Net::Google::Calendar::Entry->new();
	   $entry->title($title);
	   $entry->content("My content");
	   $entry->location('London, England');
	   $entry->transparency('transparent');
	   $entry->status('confirmed');
	   $entry->when(DateTime->now, DateTime->now() + DateTime::Duration->new( hours	=> 6 ) );

	   my $author =	Net::Google::Calendar::Person->new();
	   $author->name('Foo Bar');
	   $author->email('foo@bar.com');
	   $entry->author($author);

       By default new or updated entries are modified in place with any	new
       information provided by Google.

	  $cal->add_entry($entry);

	  $entry->content('Updated');
	  $cal->update_entry($entry);

	  $cal->delete_entry($entry);

       However if you don't want the entry updated in place pass
       "no_event_modification" in to the "new()" method.

	   my $cal = Net::Google::Calendar->new( no_event_modification => 1 );
	   $cal->login($user, $pass);

	   my $tmp = $cal->add_entry($entry);
	   die "Couldn't add event: $@\n" unless defined $tmp;

	   print "Events=".scalar($cal->get_events())."\n";

	   $tmp->content('Updated');

	   $tmp	= $cal->update_entry($tmp) || die "Couldn't update ".$tmp->id.": $@\n";

	   $cal->delete_entry($tmp) || die "Couldn't delete ".$tmp->id.": $@\n";

DESCRIPTION
       Interact	with Google's new calendar using the GData API.

AUTHENTICATION AND READ-WRITE CALENDARS
       There are effectively four ways to get events from a Google calendar.

       You can get any public events by	querying

	   http://www.google.com/calendar/feeds/<email>/public/full

       Then there are the three	ways to	get private entries. The first of
       these involves a	magic cookie in	the url	like this:

	   http://www.google.com/calendar/feeds/<email>/private-<key>/full

       Google has information on how to	find this url here

	   http://code.google.com/apis/calendar/developers_guide_protocol.html#find_feed_url

       To use either the private or public feeds do

	   my $cal = Net::Google::Calendar->new( url =>	$url);

       Both these feeds	will be	read only however. This	means that you won't
       be able to add, update or delete	entries.

       You can also get	all the	private	entries	in a read-write	feed by	either
       logging in or using "AuthSub".

       Logging in is the easiest. Simply do

	    my $cal = Net::Google::Calendar->new;
	    $cal->login($username, $password);

       Where $username and $password are the same as if	you were logging into
       the Google Calendar site.

       Alternatively if	you don't want to use username and password (if, for
       example you were	providing Calendar reading as a	service	on your
       website and didn't want to have to ask your users for their Google
       login details) you can use "AuthSub".

	    http://code.google.com/apis/accounts/AuthForWebApps.html

       Once you	have an	AuthSub	token (or you user has supplied	you with one)
       then you	can login using

	    my $cal = Net::Google::Calendar->new;
	    $cal->auth($username, $token);

METHODS
   new <opts>
       Create a	new instance. "opts" is	a hash which must contain your private
       Google url as the key "url" unless you plan to log in or	authenticate.

       See

	   http://code.google.com/apis/gdata/calendar.html#find_feed_url

       for how to get that.

       If you pass the option "no_event_modification" as a psotive value then
       add_entry and update_entry will not modify the entry in place.

   login <username> <password> [opt[s]]
       Login to	google.

       Can optionally take a hash of options which will	override the default
       login params.

       service
	   Name	of the Google service for which	authorization is requested.

	   Defaults to 'cl' for	calendar.

       source
	   Short string	identifying your application, for logging purposes.

	   Defaults to 'Net::Google::Calendar-<VERSION>'

       accountType
	   Type	of account to be authenticated.

	   Defaults to 'HOSTED_OR_GOOGLE'.

       See
       http://code.google.com/apis/accounts/AuthForInstalledApps.html#ClientLogin
       for more	details.

   auth	<username> <token>
       Use the AuthSub method for calendar access.  See
       http://code.google.com/apis/accounts/AuthForWebApps.html	for details.

   oauth Net::Google::OAuth
       Use OAuth for calendar access

   auth_object [Net::Google::AuthSub]
       Get or set the current "Net::Google::AuthSub" object.

   ssl bool
       Use ssl or not.	Auth tokens (AuthSub and OAuth)	have a scope that
       includes	http://	or https://.  Make sure	you use	ssl(1) if your scope
       is https://www.google.com/calendar/feeds/.

   get_events [	%opts ]
       Return a	list of	Net::Google::Calendar::Entry objects;

       You can pass in a hash of options which map to the Google Data API's
       generic searching mechanisms plus the specific calendar ones.

       See

	   http://code.google.com/apis/gdata/protocol.html#query-requests

       for more	details.

       q   Full-text query string

	   When	creating a query, list search terms separated by spaces, in
	   the form q=term1 term2 term3. (As with all of the query parameter
	   values, the spaces must be URL encoded.) The	GData service returns
	   all entries that match all of the search terms (like	using AND
	   between terms). Like	Google's web search, a GData service searches
	   on complete words (and related words	with the same stem), not
	   substrings.

	   To search for an exact phrase, enclose the phrase in	quotation
	   marks:

	       q => '"exact phrase'

	   To exclude entries that match a given term, use the form

	       q => '-term'

	   The search is case-insensitive.

	   Example: to search for all entries that contain the exact phrase
	   'Elizabeth Bennet' and the word 'Darcy' but don't contain the word
	   'Austen', use the following query:

	       q => '"Elizabeth	Bennet"	Darcy -Austen'

       category
	   Category filter

	   To search in	just one category do

	       category	=> 'Fritz'

	   You can query on multiple categories	by listing multiple category
	   parameters. For example

	       category	=> [ 'Fritz', 'Laurie' ]

	   returns entries that	match both categories.

	   To do an OR between terms, use a pipe character (|).	For example

	       category	=> 'Fritz|Laurie'

	   returns entries that	match either category.

	   To exclude entries that match a given category, use the form

	       category	=> '-categoryname'

	   You can, of course, mix and match

	       [ 'Jo', 'Fritz|Laurie', '-Simon'	]

	   means in category

	       (Jo AND ( Fritz OR Laurie ) AND (NOT Simon))

       author
	   Entry author

	   The service returns entries where the author	name and/or email
	   address match your query string.

       updated-min
       updated-max
	   Bounds on the entry publication date.

	   Use DateTime	objects	or the RFC 3339	timestamp format. For example:
	   2005-08-09T10:57:00-08:00.

	   The lower bound is inclusive, whereas the upper bound is exclusive.

       start-min
       start-max
	   Respectively, the earliest event start time to match	(If not
	   specified, default is 1970-01-01) and the latest event start	time
	   to match (If	not specified, default is 2031-01-01).

	   Use DateTime	objects	or the RFC 3339	timestamp format. For example:
	   2005-08-09T10:57:00-08:00.

	   The lower bound is inclusive, whereas the upper bound is exclusive.

       start-index
	   1-based index of the	first result to	be retrieved

	   Note	that this isn't	a general cursoring mechanism. If you first
	   send	a query	with

	       start-index => 1,
	       max-results => 10

	   and then send another query with

	       start-index => 11,
	       max-results => 10

	   the service cannot guarantee	that the results are equivalent	to

	       start-index => 1
	       max-results => 20

	   because insertions and deletions could have taken place in between
	   the two queries.

       max-results
	   Maximum number of results to	be retrieved.

	   For any service that	has a default max-results value	(to limit
	   default feed	size), you can specify a very large number if you want
	   to receive the entire feed.

       entryID
	   ID of a specific entry to be	retrieved.

	   If you specify an entry ID, you can't specify any other parameters.

   add_entry <Net::Google::Calendar::Entry>
       Create a	new entry.

       Returns the new entry with extra	data provided by Google	but will also
       modify the entry	in place unless	the "no_event_modification" option is
       passed to "new()".

       Returns undef on	failure.

   delete_entry	<Net::Google::Calendar::Entry>
       Delete a	given entry.

       Returns undef on	failure	or the old entry on success.

   update_entry	<Net::Google::Calendar::Entry>
       Update a	given entry.

       Returns the updated entry with extra data provided by Google but	will
       also modify the entry in	place unless the "no_event_modification"
       option is passed	to "new()".

       Returns undef on	failure.

   get_calendars <owned>
       Get a list of all of a user's Calendars as
       "Net::Google::Calendar::Calendar" objects.

       If "owned" is true then only get	the ones a user	owns.

   get_feed [feed] [opt[s]]
       If "feed" is a "URI" object then	feed is	fetch remotely.	 Otherwise it
       is assumed to be	XML data and is	parsed.

       Returns an "XML::Atom::Feed" object.

   update_feed <feed>
       Take an "XML::Atom::Feed" object	with a
       "http://schemas.google.com/g/2005#post" link and	post it.

   set_calendar	<Net::Google::Calendar::Calendar>
       Set the current calendar	to use.

   add_calendar	 <Net::Google::Calendar::Calendar>
       Create a	new calendar

       Returns the new calendar	with extra data	provided by Google but will
       also modify the entry in	place unless the "no_event_modification"
       option is passed	to "new()".

       Returns undef on	failure.

   update_calendar  <Net::Google::Calendar::Calendar>
       Update a	calendar.

       Returns the updated calendar with extra data provided by	Google but
       will also modify	the entry in place unless the "no_event_modification"
       option is passed	to "new()".

       Returns undef on	failure.

   delete_calendar <Net::Google::Calendar::Calendar> [force]
       Delete a	given calendar.

       Returns undef on	failure	or the old entry on success.

       Note that, at the moment, only "Calendar" objects returned by
       "get_calendars" with the	"owned"	parameter set to "true"	can be deleted
       (unlike editing - I don't know if this is a Google bug or not).

       However,	you can	pass in	an optional true "force" parameter to this
       method that will	allow "Calendar" objects returned by "get_calendars"
       where no	positive "owned" paramemter was	passed to be deleted. It uses
       an egregious hack though	and might suddenly stop	working	if Google
       change things or	I suddenly decide to remove it.

WARNING
       This is ALPHA level software.

       Don't use it. Ever. Or something.

TODO
       Abstract	this out to Net::Google::Data

LATEST VERSION
       The latest version can always be	obtained from my Subversion
       repository.

	   http://svn.unixbeard.net/simon/Net-Google-Calendar

AUTHOR
       Simon Wistow <simon@thegestalt.org>

COPYRIGHT
       Copyright Simon Wistow, 2006

       Distributed under the same terms	as Perl	itself.

SEE ALSO
       http://code.google.com/apis/gdata/calendar.html

perl v5.24.1			  2017-07-03	      Net::Google::Calendar(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHENTICATION AND READ-WRITE CALENDARS | METHODS | WARNING | TODO | LATEST VERSION | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::Google::Calendar&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help