calendarmodule.cpp

python s60 1.4.5版本的源代码

/*
 * ====================================================================
 * calendarmodule.cpp
 * 
 * Python API to Series 60 agenda database.
 *
 * Implements currently (30.05.2005) following Python methods and types:
 *
 * open()
 * - open the default calendar database.
 * open(<filename>)
 * - open the specified calendar database.
 * open(<filename>, 'c')
 * - open the specified calendar database. create if does not exist.
 * open(<filename>, 'n')
 * - create new, empty calendar database.
 *
 * CalendarDb
 *  add_entry()
 *  - create new entry. note that the entry is not added and saved 
 *    into the database unless entry.commit() is called.
 *  find_instances(float, float, unicode [, int])
 *  - parameters: start datetime, end datetime, search string, filter.
 *  - returns list that contains entry instances found in the search.
 *    however, note that all the returned instances occur in the same day
 *    (the first day between start and end datetime that contains instances).
 *    to search all instances between (initial) start and end datetime user 
 *    may have to execute several searches (and change the start datetime for
 *    each search). 
 *    match is detected if search string is a substring of entry's content.
 *    if filter is given in the optional int parameter the search 
 *    is reduced to entry types specified by the filter.
 *  monthly_instances(float)
 *  - parameters: datetime
 *  - returns list that contains entry instances occurring during the specified
 *    calendar month.
 *  daily_instances(float)
 *  - parameters: datetime
 *  - returns list that contains entry instances occurring during the specified
 *    day.
 *  todos_in_list(int)
 *  - parameters: todo list id
 *  - returns list that contains todo entries in the specified todo list.
 *  todo_lists() 
 *  - returns dictionary that contains todo lists (todo list id as a key
 *    and todo list name as a value)
 *  add_todo_list([unicode])
 *  - creates new todo list.
 *  - parameters: todo list name (optional)
 *  - returns id of the created todo list
 *  rename_todo_list(int, unicode)
 *  - renames specified todo list.
 *  - parameters: todo list id, new name of the todo list
 *  remove_todo_list(int)
 *  - removes specified todo list. note that the todo entries in the todo list
 *    are not deleted.
 *  - parameters: todo list id
 *  export_vcals(tuple<int,..>)
 *  - returns vcalendar string that contains specified entries.
 *  - parameters: tuple containing entry ids of exported entries
 *  import_vcals(string)
 *  - imports vcalendar entries (given in the string parameter) to the database. 
 *  - returns tuple that contains unique ids of the imported entries.
 *  replication()
 *  - returns entry's replication status.
 *  set_replication()
 *  - sets entry's replication status (EOpen, EPrivate, ERestricted).
 *  default_todo_list()
 *  -returns the id of the default todo list.
 *  
 *
 * EntryIterator
 *  next()
 *  - returns next entry id.
 *
 * Entry
 *  content()
 *  - returns entry's content text (unicode).
 *  set_content(unicode)
 *  - sets entry's content text (unicode).
 *  type()
 *  - returns entry's type (int): entry_type_appt, entry_type_event, entry_type_anniv or entry_type_todo
 *  commit()
 *  - saves the entry (or adds the entry into the database [in case of new entry]).
 *  - returns the id of the entry.
 *  set_repeat_data(dictionary)
 *  - sets the repeat data of the entry.
 *  - parameters: repeat data. contains all the repeat rules. see the further information below.
 *  repeat_data()
 *  - returns the repeat data of the entry.
 *  set_location(unicode)
 *  - sets entry's location data (the meeting room etc.)
 *  - parameters: the location.
 *  location()
 *  - returns entry's location data (unicode)
 *  set_start_and_end_datetime(float, float)
 *  - sets start datetime and end datetime of the entry.
 *  - parameters: start datetime, end datetime
 *  start_datetime()
 *  - returns start datetime (float) of the entry.
 *  end_datetime()
 *  - returns end datetime (float) of the entry.
 *  unique_id()
 *  - returns unique id of the entry
 *  last_modified()
 *  - returns datetime (float) of the entry's last modification (universal time).
 *  set_alarm(float)
 *  - sets alarm for the entry (or removes if the parameter equals to 0).
 *  - parameters: datetime of the alarm. see the further information below to check
 *    the restrictions of the alarm datetime. 
 *  has_alarm()
 *  - returns 0 if the entry is not alarmed, otherwise <> 0.
 *  alarm_datetime()
 *  - returns alarm datetime (float) of this entry.
 *  cancel_alarm()
 *  - cancels entry's alarm.
 *  set_priority(int)
 *  - sets the priority of the entry (1=high, 2=medium, 3=low)
 *  - parameters: the priority
 *  priority()
 *  - returns entry's priority.
 *  set_todo_list(int)
 *  - sets the todo list of the entry (todo entries only).
 *  - parameter: the todo list id
 *  todo_list_id()
 *  - returns the id of the todo list that contains this entry (todo entries only).
 *  set_crossed_out(float)
 *  - sets the crossed out value for the entry. if the entry is a todo then
 *    the parameter must represent a valid datetime value (cross out datetime) or
 *    equal to 0. in case of other entry types there is no restrictions for the value.
 *    if the value equals to 0 the entry is uncrossed out, otherwise it is crossed out.
 *  - parameters: crossed out datetime
 *  is_crossed_out()
 *  - returns 0 if the entry is not crossed out, otherwise <> 0
 *  crossed_out_date()
 *  - returns datetime (float) of the cross out (this is for todos only).
 *  make_undated()
 *  - makes todo entry undated (removes start and end dates and repeat rules)
 *  is_dated()
 *  - returns information whether the todo entry is dated (or undated).
 *
 * FURTHER INFORMATION:
 *
 *
 *
 * repeat rules:
 * - repeat rules specify entry's repeat status. this is much like the "recurrence" functionality
 *   in outlook's calendar appointment. 
 * - there are 6 repeat types: daily, weekly, monthly_by_dates, monthly_by_days, 
 *   yearly_by_date and yearly_by_day.
 *   - daily: repeated daily
 *   - weekly_by_days: repeat on the specified days of the week (like monday and wednesday etc.)
 *   - monthly_by_dates: repeat monthly on the specified dates (like 15th and 17th day of the month)
 *   - monthly_by_days: repeat monthly on the specified days (like fourth wednesday of the month,
 *     last monday of the month)
 *   - yearly_by_date: repeat yearly on the specified date (like 24th December)
 *   - yearly_by_day: repeat yearly on the specified day (like every third tuesday of may).
 * - there are exceptions e.g. you can specify datetime (float) such that there is no repeat of 
 *   the entry that day even if the repeat rule would specify that there is.
 * - you must set the start_date and end_date (floats) of the repeat, and you can set interval 
 *   (how often repeat occurs e.g. in case of daily repeat 1=every day, 2=every second day etc.), 
 *   and the "days"-specifier which lets you explicitely specify the repeat days (e.g in 
 *   case of weekly-repeat you can set "days":[0,2] which sets the repeat to occur these days
 *   (monday,wednesday). if you do not set the "days"-specifier it is calculated automatically
 *   using the start_date-value).
 * - note that you can modify repeat data by calling rep_data = entry.repeat_data(), then making
 *   changes to rep_data and then calling entry.set_repeat_data(rep_data).
 *
 * - repeat definition examples:
 *
 * repeat = {"type":"daily", #repeat type
 *           "exceptions":[exception_day, exception_day+2*24*60*60], #no appointment those days 
 *           "start":appt_start_date, #start of the repeat
 *           "end":appt_start_date+30*24*60*60, #end of the repeat
 *           "interval":1} #interval (1=every day, 2=every second day etc.)
 * 
 * repeat = {"type":"weekly", #repeat type
 *           "days":[0,1], #which days in a week (monday,tuesday)
 *           "exceptions":[exception_day], #no appointment that day 
 *           "start":appt_start_date, #start of the repeat
 *           "end":appt_start_date+30*24*60*60, #end of the repeat
 *           "interval":1} #interval (1=every week, 2=every second week etc.) 
 *
 * repeat = {"type":"monthly_by_days", #repeat type
 *           # appointments on second tuesday and last monday of the month
 *           "days":[{"week":1, "day":1},{"week":4, "day":0}],
 *           "exceptions":[exception_day], #no appointment that day 
 *           "start":appt_start_date, #start of the repeat
 *           "end":appt_start_date+30*24*60*60, #end of the repeat
 *           "interval":1} #interval (1=every month, 2=every second month etc.)
 *
 * repeat = {"type":"monthly_by_dates", #repeat type
 *           "days":[0,15], # appointments on first and 14th day of the month. 
 *           "exceptions":[exception_day], #no appointment that day 
 *           "start":appt_start_date, #start of the repeat
 *           "end":appt_start_date+30*24*60*60, #end of the repeat
 *           "interval":1} #interval (1=every month, 2=every second month etc.)
 *
 * repeat = {"type":"yearly_by_date", #repeat type
 *           "exceptions":[exception_day], #no appointment that day 
 *           "start":appt_start_date, #start of the repeat
 *           "end":appt_start_date+3*365*24*60*60, #end of the repeat
 *           "interval":1} #interval (1=every year, 2=every second year etc.)
 *
 * repeat = {"type":"yearly_by_day", #repeat type
 *           # appointments on second tuesday of february
 *           "days":{"day":1, "week":1, "month":1},
 *           "exceptions":[exception_day], #no appointment that day 
 *           "start":appt_start_date, #start of the repeat
 *           "end":appt_start_date+3*365*24*60*60, #end of the repeat
 *           "interval":1} #interval (1=every year, 2=every second year etc.)
 *
 *
 *
 * QUIRKS:
 *
 * -alarms can be set for all entry types but they work only with appointments and anniversaries
 *  (compare: with nokias native applications you cannot set an alarm for memos (=events) or todos).
 *
 * -if you press snooze when the phone alarms and then cancel the alarm it will still alarm after snoozing although
 *  the alarm has been cancelled (again, this is just how nokias native calendar application behaves).
 *
 * -if you use other than the default database alarms will not work (you can set them but they do nothing).
 *
 * -if you set an alarm after appoinment's start beware that the native calendar application tries
 *  to change the alarm time (to precede the appointment by 15 minutes).
 *
 * set_alarm:
 * - it seems that alarm can be set 1001 days before the entrys start day 
 *   (except with todo. with todo it is 1001 days before the entrys end day [due date])
 * - it seems the alarm can be set 23h 59 min after the entrys start datetime for appt
 *   (but if the date of the alarm is greater than entry's start date an "overflow" of the 
 *   alarm time occurs e.g. if the entry starts at 23.50 and alarm is set 20 minutes later
 *   the symbian api sets the alarm to occur at 00.10 on the same day as the entry starts!
 *   the alarm is therefore set 23h and 40min before(!) the entry's start!. To avoid this mess
 *   this extension checks that the alarm occurs earlier or on the same day as 
 *   the entry starts. otherwise an exception is raised.).
 *   for other entry types the the alarm can be set as much after the start datetime 
 *   (end/due datetime for todo's) as there is time left within that same day. this extension
 *   checks the alarm datetime similarly in case of any entry type. 
 *
 *
 *
 *
 * Copyright (c) 2005-2007 Nokia Corporation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * ====================================================================
 */


#include "calendarmodule.h"
 


//////////////GENERAL FUNCTIONS///////////////

TReal time_UTC_as_UTC_TReal(const TTime& aTime)
{

    return (aTime.Int64().GetTReal()-epoch_as_TReal())/
           (1000.0*1000.0);
}

void pythonRealUtcAsTTime(TReal timeValue, TTime& theTime)
{
    TInt64 timeInt(timeValue*(1000.0*1000.0)+epoch_as_TReal());
    theTime = timeInt;
}

PyObject * ttimeAsPythonFloatUtc(const TTime& timeValue)
{  
	return Py_BuildValue("d",time_UTC_as_UTC_TReal(timeValue));
}

  
/*
 * Returns date value to corresponds the given datetime value.
 */
TTime truncToDate(const TTime& theTime)
{
  TDateTime aDateTime = theTime.DateTime();
  aDateTime.SetHour(0); 
  aDateTime.SetMinute(0); 
  aDateTime.SetSecond(0); 
  return TTime(aDateTime);
}


/*
 * Tests if the file exists.
 */
TBool testFileExistenceL(TDesC& filename){
  TBool fileExists = EFalse;
  RFs fileSession;
  User::LeaveIfError(fileSession.Connect());
  CleanupClosePushL(fileSession);
  fileExists = BaflUtils::FileExists(fileSession, filename);
  CleanupStack::PopAndDestroy(); // Close fileSession.
  return fileExists;
}


/*
 * Creates new agenda file.
 */
void createNewAgendaFileL(TDesC& filename){
  RFs fileSession;
  User::LeaveIfError(fileSession.Connect());
  CleanupClosePushL(fileSession);
  TFileName aFilename(filename);
  CParaFormatLayer* paraFormatLayer = CParaFormatLayer::NewL();
  CleanupStack::PushL(paraFormatLayer);
  CCharFormatLayer* charFormatLayer = CCharFormatLayer::NewL();
  CleanupStack::PushL(charFormatLayer);

  CAgnModel* agendaModel = CAgnModel::NewL(NULL);
  CleanupStack::PushL(agendaModel);
  agendaModel->CreateL(fileSession, 
               aFilename,
               KDefaultTodoListName, 
               paraFormatLayer, 
               charFormatLayer);

  CleanupStack::PopAndDestroy(); // agendaModel. 
  CleanupStack::PopAndDestroy(); // charFormatLayer. 
  CleanupStack::PopAndDestroy(); // paraFormatLayer. 
  CleanupStack::PopAndDestroy(); // Close fileSession.  
}


/*
 * Checks if the value represents a weekday.
 */
TBool isWeekday(TInt value)
{
  TBool retVal = ETrue;
  switch(value){
    case EMonday:
    break;
    case ETuesday:
    break;
    case EWednesday:
    break; 
    case EThursday:
    break;
    case EFriday:
    break;
    case ESaturday:
    break;
    case ESunday:
    break;
    default:
      retVal = EFalse;
    break;
  }
  return retVal;
}


/*
 * Checks if the value represents a weeknumber (in month).
 */
TBool isWeekInMonth(TInt value)
{
  TBool retVal = ETrue;
  switch(value){
    case TAgnRpt::EFirst:
    break;
    case TAgnRpt::ESecond:
    break;
    case TAgnRpt::EThird:
    break;
    case TAgnRpt::EFourth:
    break;
    case TAgnRpt::ELast:
    break;
    default:
      retVal = EFalse;
    break;
  }
  return retVal;
}


/*
 * Checks if the value represents a month.
 */
TBool isMonth(TInt value)
{
  TBool retVal = ETrue;
  switch(value){
    case EJanuary:
    break;
    case EFebruary:
    break;
    case EMarch:
    break;
    case EApril:
    break;
    case EMay:
    break;
    case EJune:
    break;
    case EJuly:
    break;
    case EAugust:
    break;
    case ESeptember:
    break;
    case EOctober:
    break;
    case ENovember:
    break;
    case EDecember:
    break;
    default:
      retVal = EFalse;
    break;
  }
  return retVal;
}


/*
 * Checks if the time value is in the limits of agenda model (and not null).
 */
TBool Check_time_validity(const TTime& theTime)
{
  if(AgnDateTime::MaxDateAsTTime()<theTime || 
    AgnDateTime::MinDateAsTTime()>theTime ||
    AgnDateTime::TTimeToAgnDate(theTime)==AgnDateTime::NullDate()){
    return EFalse; // Illegal time value.
  }else{
    return ETrue;