gcal4ruby 0.1.0

data/README

@@ -0,0 +1,83 @@
+#=GCal4Ruby
+#
+#==Introduction
+#GCal4Ruby is a full featured wrapper for the google calendar API.  GCal4Ruby implements
+#all of the functionality available through the Google Calnedar API, including permissions,
+#attendees, reminders and event recurrence.  
+#
+#==Author and Contact Information
+#GCal4Ruby was created and is maintained by {Mike Reich}[mailto:mike@seabourneconsulting.com] 
+#and is licenses under the GPL v2.  Feel free to use and update, but be sure to contribute your
+#code back to the project and attribute as required by the license.
+#
+#==Description
+#GCal4Ruby has three major components: the service, calendar and event objects.  Each service
+#has many calendars, which in turn have many events.  Each service is the representation of a
+#google account, and thus must be successfully authenticated using valid Google Calendar
+#account credentials.  
+#
+#==Examples
+#Below are some common usage examples.  For more examples, check the documentation.
+#===Service
+#1. Authenticate
+#    service = Service.new
+#    service.authenticate("user@gmail.com", "password")
+#
+#2. Get Calendar List
+#    calendars = service.calendars
+#
+#===Calendar
+#All usages assume a successfully authenticated Service.
+#1. Create a new Calendar
+#    cal = Calendar.new(service)
+#
+#2. Find an existing Calendar
+#    cal = Calendar.find(service, "New Calendar", :first)
+#
+#3. Find all calendars containing the search term
+#    cal = Calendar.find(service, "Soccer Team")
+#
+#4. Find a calendar by ID
+#    cal = Calendar.find(service, id, :first)
+#===Event
+#All usages assume a successfully authenticated Service and valid Calendar.
+#1. Create a new Event
+#    event = Event.new(calendar)
+#    event.title = "Soccer Game"
+#    event.start = Time.parse("12-06-2009 at 12:30 PM")
+#    event.end = Time.parse("12-06-2009 at 1:30 PM")
+#    event.where = "Merry Playfields"
+#    event.save
+#
+#2. Find an existing Event
+#    event = Event.find(cal, "Soccer Game", :first)
+#
+#3. Find all events containing the search term
+#    event = Event.find(cal, "Soccer Game")
+#
+#4. Create a recurring event for every saturday
+#    event = Event.new(calendar)
+#    event.title = "Baseball Game"
+#    event.where = "Municipal Stadium"
+#    event.recurrence = Recurrence.new
+#    event.recurrence.start = Time.parse("13-06-2009 at 4:30 PM")
+#    event.recurrence.end = Time.parse("13-06-2009 at 6:30 PM")
+#    event.recurrence.frequency = {"weekly" => ["SA"]}
+#    event.save 
+#
+#5. Create an event with a 15 minute email reminder
+#    event = Event.new(calendar)
+#    event.title = "Dinner with Kate"
+#    event.start = Time.parse("20-06-2009 at 5 pm")
+#    event.end = Time.parse("20-06-209 at 8 pm")
+#    event.where = "Luigi's"
+#    event.reminder = {:minutes => 15, :method => 'email'}
+#    event.save
+#
+#6. Create an event with attendees
+#    event = Event.new(calendar)
+#    event.title = "Dinner with Kate"
+#    event.start = Time.parse("20-06-2009 at 5 pm")
+#    event.end = Time.parse("20-06-209 at 8 pm")
+#    event.attendees => {:name => "Kate", :email => "kate@gmail.com"}
+#    event.save

data/lib/gcal4ruby/base.rb

@@ -0,0 +1,256 @@
+require "rexml/document"
+require "cgi"
+require "uri"
+require "net/http"
+require "net/https"
+require "open-uri"
+require "nkf"
+require "time"
+
+Net::HTTP.version_1_2
+
+# GCal4Ruby is a full featured wrapper for the google calendar API
+
+# =Usage:
+
+module GCal4Ruby
+  
+  CALENDAR_XML = "<entry xmlns='http://www.w3.org/2005/Atom' 
+       xmlns:gd='http://schemas.google.com/g/2005' 
+       xmlns:gCal='http://schemas.google.com/gCal/2005'>
+  <title type='text'></title>
+  <summary type='text'></summary>
+  <gCal:timezone value=''></gCal:timezone>
+  <gCal:hidden value=''></gCal:hidden>
+  <gCal:color value=''></gCal:color>
+  <gd:where rel='' label='' valueString=''></gd:where>
+  </entry>"
+  
+  ACL_XML = "<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gAcl='http://schemas.google.com/acl/2007'>
+                      <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule'/>
+                       <gAcl:scope type='default'></gAcl:scope>
+                       <gAcl:role value=''></gAcl:role>
+                    </entry>"
+                    
+  EVENT_XML = "<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'>
+  <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/g/2005#event'></category>
+  <title type='text'></title>
+  <content type='text'></content>
+  <gd:transparency value=''></gd:transparency>
+  <gd:eventStatus value=''></gd:eventStatus>
+  <gd:where valueString=''></gd:where>
+  <gd:when startTime='' endTime=''></gd:when>
+</entry>
+  "
+  
+  class AuthenticationFailed < StandardError; end #:nodoc: all
+
+  class NotAuthenticated < StandardError; end
+    
+  class InvalidService < StandardError; end
+    
+  class HTTPPostFailed < StandardError; end
+    
+  class HTTPPutFailed < StandardError; end
+    
+  class HTTPGetFailed < StandardError; end
+    
+  class HTTPDeleteFailed < StandardError; end
+    
+  class CalendarSaveFailed < StandardError; end
+  
+  class EventSaveFailed < StandardError; end
+    
+  class RecurrenceValueError < StandardError; end
+
+  #The ProxyInfo class contains information for configuring a proxy connection
+
+  class ProxyInfo
+    attr_accessor :address, :port, :username, :password
+    @address = nil
+    @port = nil
+    @username = nil
+    @password = nil
+
+    #The initialize function accepts four variables for configuring the ProxyInfo object.  
+    #The proxy connection is initiated using the builtin Net::HTTP proxy support.
+
+    def initialize(address, port, username=nil, password=nil)
+      @address = address
+      @port = port
+      @username = username
+      @password = password
+    end
+  end
+  
+  #The Base class includes the basic HTTP methods for sending and receiving 
+  #messages from the Google Calendar API.  You shouldn't have to use this class 
+  #directly, rather access the functionality through the Service subclass.
+
+  class Base
+    AUTH_URL = "https://www.google.com/accounts/ClientLogin"
+    CALENDAR_LIST_FEED = "http://www.google.com/calendar/feeds/default/allcalendars/full"
+    @proxy_info = nil
+    @auth_token = nil
+    @debug = false
+
+    #Contains the ProxyInfo object for using a proxy server
+    attr_accessor :proxy_info
+    
+    #If set to true, debug will dump all raw HTTP requests and responses
+    attr_accessor :debug
+    
+    # Sends an HTTP POST request.  The header should be a hash of name/value pairs.  
+    # Returns the Net::HTTPResponse object on succces, or raises the appropriate
+    # error if a non 20x response code is received.
+    def send_post(url, content, header=nil)
+      header = auth_header(header)
+      ret = nil
+      location = URI.parse(url)
+      https = get_http_object(location)
+      puts "url = "+url if @debug
+      if location.scheme == 'https'
+        puts "SSL True" if @debug
+      	https.use_ssl = true
+      	https.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      puts "Starting post\nHeader: #{header}\nContent: #{content}" if @debug
+      https.start do |http|
+        ret = http.post(location.path, content, header)
+      end
+      while ret.is_a?(Net::HTTPRedirection)
+        puts "Redirect recieved, resending post" if @debug
+        https.start do |http|
+          ret = http.post(ret['location'], content, header)
+        end
+      end
+      if ret.is_a?(Net::HTTPSuccess)
+        puts "20x response recieved\nResponse: \n"+ret.read_body if @debug
+        return ret
+      else
+        puts "invalid response received: "+ret.code if @debug
+        raise HTTPPostFailed, ret.body
+      end
+    end
+    
+    # Sends an HTTP PUT request.  The header should be a hash of name/value pairs.  
+    # Returns the Net::HTTPResponse object on succces, or raises the appropriate
+    # error if a non 20x response code is received.
+    def send_put(url, content, header=nil)
+      header = auth_header(header)
+      ret = nil
+      location = URI.parse(url)
+      https = get_http_object(location)
+      puts "url = "+url if @debug
+      if location.scheme == 'https'
+        puts "SSL True" if @debug
+        https.use_ssl = true
+        https.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      puts "Starting post\nHeader: #{header}\nContent: #{content}" if @debug
+      https.start do |http|
+        ret = http.put(location.path, content, header)
+      end
+      while ret.is_a?(Net::HTTPRedirection)
+        puts "Redirect recieved, resending post" if @debug
+        https.start do |http|
+          ret = http.put(ret['location'], content, header)
+        end
+      end
+      if ret.is_a?(Net::HTTPSuccess)
+        puts "20x response recieved\nResponse: \n"+ret.read_body if @debug
+        return ret
+      else
+        puts "invalid response received: "+ret.code if @debug
+        raise HTTPPutFailed, ret.body
+      end
+    end
+
+    # Sends an HTTP GET request.  The header should be a hash of name/value pairs.  
+    # Returns the Net::HTTPResponse object on succces, or raises the appropriate
+    # error if a non 20x response code is received.
+    def send_get(url, header = nil)
+      header = auth_header(header)
+      ret = nil
+      location = URI.parse(url)
+      http = get_http_object(location)
+      puts "url = "+url if @debug
+      if location.scheme == 'https'
+        puts "SSL True" if @debug
+        https.use_ssl = true
+        https.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      puts "Starting post\nHeader: #{header}\n" if @debug
+      http.start do |http|
+        ret = http.get(location.path, header)
+      end
+      while ret.is_a?(Net::HTTPRedirection)
+        puts "Redirect recieved, resending post" if @debug
+    	  http.start do |http|
+    	    ret = http.get(ret['location'], header)
+    	  end
+      end
+      if ret.is_a?(Net::HTTPSuccess)
+        puts "20x response recieved\nResponse: \n"+ret.read_body if @debug
+        return ret
+      else
+        puts "Redirect recieved, resending post" if @debug
+        raise HTTPGetFailed, ret.body
+      end
+    end
+
+    # Sends an HTTP DELETE request.  The header should be a hash of name/value pairs.  
+    # Returns the Net::HTTPResponse object on succces, or raises the appropriate
+    # error if a non 20x response code is received.
+    def send_delete(url, header = nil)
+      header = auth_header(header)
+      ret = nil
+      location = URI.parse(url)
+      https = get_http_object(location)
+      puts "url = "+url if @debug
+      if location.scheme == 'https'
+        puts "SSL True" if @debug
+        https.use_ssl = true
+        https.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      puts "Starting post\nHeader: #{header}\n" if @debug
+      https.start do |http|
+        ret = http.delete(location.path, header)
+      end
+      while ret.is_a?(Net::HTTPRedirection)
+        puts "Redirect recieved, resending post" if @debug
+        https.start do |http|
+          ret = http.delete(ret['location'], header)
+        end
+      end
+      if ret.is_a?(Net::HTTPSuccess)
+        puts "20x response recieved\nResponse: \n"+ret.read_body if @debug
+        return true
+      else
+        puts "invalid response received: "+ret.code if @debug
+        raise HTTPDeleteFailed, ret.body
+      end
+    end
+
+    private
+
+    def get_http_object(location)
+      if @proxy_info and @proxy_info.address
+	     return Net::HTTP.new(location.host, location.port, @proxy_info.address, @proxy_info.port, @proxy_info.username, @proxy_info.password)
+      else
+	     return Net::HTTP.new(location.host, location.port)
+      end      
+    end
+
+    def auth_header(header)
+      if @auth_token
+      	if header
+      	  header.merge!({'Authorization' => "GoogleLogin auth=#{@auth_token}", "GData-Version" => "2.1"})
+      	else 
+      	  header = {'Authorization' => "GoogleLogin auth=#{@auth_token}", "GData-Version" => "2.1"}
+      	end
+      end
+      return header
+    end
+  end
+end

data/lib/gcal4ruby/calendar.rb

@@ -0,0 +1,297 @@
+require 'gcal4ruby/event'
+
+module GCal4Ruby
+#The Calendar Class is the representation of a Google Calendar.  Each user account 
+#can have multiple calendars.  You must have an authenticated Service object before 
+#using the Calendar object.
+#=Usage
+#All usages assume a successfully authenticated Service.
+#1. Create a new Calendar
+#    cal = Calendar.new(service)
+#
+#2. Find an existing Calendar
+#    cal = Calendar.find(service, "New Calendar", :first)
+#
+#3. Find all calendars containing the search term
+#    cal = Calendar.find(service, "Soccer Team")
+#
+#4. Find a calendar by ID
+#    cal = Calendar.find(service, id, :first)
+#
+#After a calendar object has been created or loaded, you can change any of the 
+#attributes like you would any other object.  Be sure to save the calendar to write changes
+#to the Google Calendar service.
+
+class Calendar
+  CALENDAR_FEED = "http://www.google.com/calendar/feeds/default/owncalendars/full"
+  
+  #The calendar title
+  attr_accessor :title
+  
+  #A short description of the calendar
+  attr_accessor :summary
+  
+  #The parent Service object passed on initialization
+  attr_reader :service
+  
+  #The unique calendar id
+  attr_reader :id
+  
+  #Boolean value indicating the calendar visibility
+  attr_accessor :hidden
+  
+  #The calendar timezone[http://code.google.com/apis/calendar/docs/2.0/reference.html#gCaltimezone]
+  attr_accessor :timezone
+  
+  #The calendar color.  Must be one of these[http://code.google.com/apis/calendar/docs/2.0/reference.html#gCalcolor] values.
+  attr_accessor :color
+  
+  #The calendar geo location, if any
+  attr_accessor :where
+  
+  #A boolean value indicating whether the calendar appears by default when viewed online
+  attr_accessor :selected
+  
+  #The event feed for the calendar
+  attr_reader :event_feed
+  
+  #Returns true if the calendar exists on the Google Calendar system (i.e. was 
+  #loaded or has been saved).  Otherwise returns false.
+  def exists?
+    return @exists
+  end
+  
+  #Returns true if the calendar is publically accessable, otherwise returns false.
+  def public?
+    return @public
+  end
+  
+  #Returns an array of Event objects corresponding to each event in the calendar.
+  def events
+    events = []
+    ret = @service.send_get(@event_feed)
+    REXML::Document.new(ret.body).root.elements.each("entry"){}.map do |entry|
+      entry.attributes["xmlns:gCal"] = "http://schemas.google.com/gCal/2005"
+      entry.attributes["xmlns:gd"] = "http://schemas.google.com/g/2005"
+      entry.attributes["xmlns"] = "http://www.w3.org/2005/Atom"
+      e = Event.new(self)
+      if e.load(entry.to_s)
+        events << e
+      end
+    end
+    return events
+  end
+  
+  #Set the calendar to public (p = true) or private (p = false).  Publically viewable
+  #calendars can be accessed by anyone without having to log in to google calendar.  See
+  #Calendar#to_iframe for options to display a public calendar in a webpage.
+  def public=(p)
+    if p
+      permissions = 'http://schemas.google.com/gCal/2005#read' 
+    else
+      permissions = 'none'
+    end
+    
+    #if p != @public
+      path = "http://www.google.com/calendar/feeds/#{@id}/acl/full/default"
+      request = REXML::Document.new(ACL_XML)
+      request.root.elements.each() do |ele|
+        if ele.name == 'role'
+          ele.attributes['value'] = permissions
+        end
+        
+      end
+      if @service.send_put(path, request.to_s, {"Content-Type" => "application/atom+xml", "Content-Length" => request.length.to_s})
+        @public = p
+        return true
+      else
+        return false
+      end
+    #end
+  end
+
+  #Accepts a Service object.  Returns the new Calendar if successful, otherwise raises the InvalidService
+  #error.
+  def initialize(service)
+    super()
+    if !service.is_a?(Service)
+      raise InvalidService
+    end
+    @xml = CALENDAR_XML
+    @service = service
+    @exists = false
+    @title = ""
+    @summary = ""
+    @public = false
+    @id = nil
+    @hidden = false
+    @timezone = "America/Los_Angeles"
+    @color = "#2952A3"
+    @where = ""
+    return true
+  end
+  
+  #Deletes a calendar.  If successful, returns true, otherwise false.  If successful, the
+  #calendar object is cleared.
+  def delete
+    if @exists    
+      if @service.send_delete(CALENDAR_FEED+"/"+@id)
+        @exists = false
+        @title = nil
+        @summary = nil
+        @public = false
+        @id = nil
+        @hidden = false
+        @timezone = nil
+        @color = nil
+        @where = nil
+        return true
+      else
+        return false
+      end
+    else
+      return false
+    end
+  end
+  
+  #If the calendar does not exist, creates it, otherwise updates the calendar info.  Returns
+  #true if the save is successful, otherwise false.
+  def save
+    if @exists
+      ret = service.send_put(@edit_feed, to_xml(), {'Content-Type' => 'application/atom+xml'})
+    else
+      ret = service.send_post(CALENDAR_FEED, to_xml(), {'Content-Type' => 'application/atom+xml'})
+    end
+    if !@exists
+      if load(ret.read_body)
+        return true
+      else
+        raise CalendarSaveFailed
+      end
+    end
+    return true
+  end
+  
+  #Class method for querying the google service for specific calendars.  The service parameter
+  #should be an appropriately authenticated Service. The term parameter can be any string.  The
+  #scope parameter may be either :all to return an array of matches, or :first to return 
+  #the first match as a Calendar object.
+  def self.find(service, query_term, scope = :all)
+    t = query_term.downcase
+    cals = service.calendars
+    ret = []
+    cals.each do |cal|
+      title = cal.title || ""
+      summary = cal.summary || ""
+      id = cal.id || ""
+      if title.downcase.match(t) or summary.downcase.match(t) or id.downcase.match(t)
+        if scope == :first
+          return cal
+        elsif scope == :all
+          ret << cal
+        end
+      end
+    end
+    ret
+  end
+  
+  #Reloads the calendar objects information from the stored server version.  Returns true
+  #if successful, otherwise returns false.  Any information not saved will be overwritten.
+  def reload
+    if not @exists
+      return false
+    end  
+    t = Calendar.find(service, @id, :first)
+    if t
+      load(t.xml)
+    else
+      return false
+    end
+  end
+  
+  #Returns the xml representation of the Calenar.
+  def to_xml
+    xml = REXML::Document.new(@xml)
+    xml.root.elements.each(){}.map do |ele|
+      case ele.name
+      when "title"
+        ele.text = @title
+      when "summary"
+        ele.text = @summary
+      when "timezone"
+        ele.attributes["value"] = @timezone
+      when "hidden"
+        ele.attributes["value"] = @hidden
+      when "color"
+        ele.attributes["value"] = @color
+      when "selected"
+        ele.attributes["value"] = @selected
+      end
+    end
+    xml.to_s
+  end
+
+  #Loads the Calendar with returned data from Google Calendar feed.  Returns true if successful.
+  def load(string)
+    @exists = true
+    @xml = string
+    xml = REXML::Document.new(string)
+    xml.root.elements.each(){}.map do |ele|
+      case ele.name
+        when "id"
+          @id = ele.text.gsub("http://www.google.com/calendar/feeds/default/calendars/", "")
+        when 'title'
+          @title = ele.text
+        when 'summary'
+          @summary = ele.text
+        when "color"
+          @color = ele.attributes['value']
+        when 'hidden'
+          @hidden = ele.attributes["value"] == "true" ? true : false
+        when 'timezone'
+          @timezone = ele.attributes["value"]
+        when "selected"
+          @selected = ele.attributes["value"] == "true" ? true : false
+        when "link"
+          if ele.attributes['rel'] == 'edit'
+            @edit_feed = ele.attributes['href']
+          end
+      end
+    end
+    
+    @event_feed = "http://www.google.com/calendar/feeds/#{@id}/private/full"
+    
+    puts "Getting ACL Feed" if @service.debug
+    ret = @service.send_get("http://www.google.com/calendar/feeds/#{@id}/acl/full/")
+    r = REXML::Document.new(ret.read_body)
+    r.root.elements.each("entry") do |ele|
+      ele.elements.each do |e|
+        #puts "e = "+e.to_s if @service.debug
+        #puts "previous element = "+e.previous_element.to_s if @service.debug
+        if e.name == 'role' and e.previous_element.name == 'scope' and e.previous_element.attributes['type'] == 'default'
+          if e.attributes['value'].match('#read')
+            @public = true
+          else
+            @public = false
+          end
+        end
+      end
+    end
+    return true
+  end
+  
+  #Returns a HTML <iframe> tag displaying the calendar.
+  def to_iframe(height=300, width=400)
+    
+  end
+  
+  private
+  @xml 
+  @exists = false
+  @public = false
+  @event_feed = ''
+  @edit_feed = ''
+  
+end 
+
+end