From 6ea598f17a97d55d2c35e47f92a1a8c5ee55be5a Mon Sep 17 00:00:00 2001 From: Jeesun Kim Date: Wed, 17 May 2017 14:33:33 +0900 Subject: [PATCH] Modify API Reference Change-Id: If1971439dc2cf742809cf2dfbe28a6b0df636e68 --- .../Tizen.Pims.Calendar/CalendarDatabase.cs | 140 ++++++++++++++++++--- .../Tizen.Pims.Calendar/CalendarErrorFactory.cs | 27 ++-- .../Tizen.Pims.Calendar/CalendarFilter.cs | 56 ++++++--- .../Tizen.Pims.Calendar/CalendarList.cs | 21 +++- .../Tizen.Pims.Calendar/CalendarManager.cs | 13 +- .../Tizen.Pims.Calendar/CalendarQuery.cs | 23 +++- .../Tizen.Pims.Calendar/CalendarRecord.cs | 51 ++++++-- .../Tizen.Pims.Calendar/CalendarReminder.cs | 24 ++-- .../Tizen.Pims.Calendar/CalendarStructs.cs | 14 ++- .../Tizen.Pims.Calendar/CalendarVcalendar.cs | 19 ++- .../Tizen.Pims.Calendar/CalendarViews.cs | 112 +++-------------- .../Tizen.Pims.Calendar/ReminderEventArgs.cs | 4 - 12 files changed, 316 insertions(+), 188 deletions(-) diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarDatabase.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarDatabase.cs index 3f1f6d5..2cbb6bf 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarDatabase.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarDatabase.cs @@ -24,20 +24,28 @@ using System.Runtime.InteropServices; /// /// The Calendar Service API provides functions and ienumerations used in the entire Content Service. /// The Information about calendar items i.e. book, event, todo, alarm, attendee and extended are managed in the database -/// and operations that involve database requires an active connection with the calendar contact service. +/// and operations that involve database requires an active connection with the calendar service. /// namespace Tizen.Pims.Calendar { /// - /// CalendarDatabase class is the interface class for managing the record from/to the database. - /// This class allows usre to access/create/update db operations for media content. + /// CalendarDatabase provides methods to manage calendar information from/to the database. /// + /// + /// This class allows usre to access/create/update db operations for calendar information. + /// public class CalendarDatabase { /// + /// Delegete for detecting the calendar database changes. /// /// The record uri + /// + /// The delegate must be registered using AddDBChangedDelegate. + /// It's invoked when the designated view changes. + /// + /// public delegate void CalendarDBChangedDelegate(string uri); private Object thisLock = new Object(); @@ -47,7 +55,7 @@ namespace Tizen.Pims.Calendar internal CalendarDatabase() { - + ///To be created in CalendarManager only } /// @@ -68,8 +76,13 @@ namespace Tizen.Pims.Calendar } /// - /// The calendar database version on the current connection. + /// Gets last successful changed calendar database version on the current connection. /// + /// The last successful changed calendar database version on the current connection + /// http://tizen.org/privilege/calendar.read + /// Thrown when method failed due to invalid operation + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public int LastChangeVersion { get @@ -88,9 +101,13 @@ namespace Tizen.Pims.Calendar /// Inserts a record into the calendar database. /// /// The record to be inserted - /// - /// The record id - /// + /// The ID of inserted record + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public int Insert(CalendarRecord record) { int id = -1; @@ -109,16 +126,27 @@ namespace Tizen.Pims.Calendar /// The view URI of a record /// The record ID /// - /// CalendarRecord instance. + /// The record associated with the record ID /// + /// http://tizen.org/privilege/calendar.read + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public CalendarRecord Get(string viewUri, int recordId) { IntPtr handle; int error = Interop.Calendar.Database.Get(viewUri, recordId, out handle); if (CalendarError.None != (CalendarError)error) { - Log.Error(Globals.LogTag, "Get Failed with error " + error); - throw CalendarErrorFactory.GetException(error); + if (CalendarError.DBNotFound == (CalendarError)error) + { + Log.Error(Globals.LogTag, "No data" + error); + return null; + } + Log.Error(Globals.LogTag, "Get Failed with error " + error); + throw CalendarErrorFactory.GetException(error); } return new CalendarRecord(handle); } @@ -127,6 +155,12 @@ namespace Tizen.Pims.Calendar /// Updates a record in the calendar database. /// /// The record to be updated + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public void Update(CalendarRecord record) { int error = Interop.Calendar.Database.Update(record._recordHandle); @@ -142,6 +176,12 @@ namespace Tizen.Pims.Calendar /// /// The view URI of a record /// The record ID to be deleted + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public void Delete(string viewUri, int recordId) { int error = Interop.Calendar.Database.Delete(viewUri, recordId); @@ -157,6 +197,12 @@ namespace Tizen.Pims.Calendar /// /// The record to be replaced /// the record id + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public void Replace(CalendarRecord record, int id) { int error = Interop.Calendar.Database.Replace(record._recordHandle, id); @@ -174,8 +220,14 @@ namespace Tizen.Pims.Calendar /// The index from which results are received /// The maximum number of results(value 0 is used for all records) /// - /// CalendarList + /// The record list /// + /// http://tizen.org/privilege/calendar.read + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public CalendarList GetAll(string viewUri, int offset, int limit) { IntPtr handle; @@ -197,6 +249,12 @@ namespace Tizen.Pims.Calendar /// /// CalendarList /// + /// http://tizen.org/privilege/calendar.read + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public CalendarList GetRecordsWithQuery(CalendarQuery query, int offset, int limit) { IntPtr handle; @@ -216,6 +274,12 @@ namespace Tizen.Pims.Calendar /// /// The inserted record id array /// + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public int[] Insert(CalendarList list) { IntPtr ids; @@ -236,6 +300,12 @@ namespace Tizen.Pims.Calendar /// Updates multiple records into the calendar database as a batch operation. /// /// The record list + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public void Update(CalendarList list) { int error = Interop.Calendar.Database.UpdateRecords(list._listHandle); @@ -251,6 +321,12 @@ namespace Tizen.Pims.Calendar /// /// The view URI of the records to delete /// The record IDs to delete + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public void Delete(string viewUri, int[] idArray) { int error = Interop.Calendar.Database.DeleteRecords(viewUri, idArray, idArray.Length); @@ -265,6 +341,12 @@ namespace Tizen.Pims.Calendar /// Deletes multiple records with related child records from the calendar database as a batch operation. /// /// The record list + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public void Delete(CalendarList list) { CalendarRecord record = null; @@ -307,6 +389,12 @@ namespace Tizen.Pims.Calendar /// /// The record list /// The record IDs + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public void Replace(CalendarList list, int[] idArray) { int error = Interop.Calendar.Database.ReplaceRecords(list._listHandle, idArray, idArray.Length); @@ -325,8 +413,14 @@ namespace Tizen.Pims.Calendar /// The calendar database version /// /// - /// CalendarList + /// The record list /// + /// http://tizen.org/privilege/calendar.read + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public CalendarList GetChangesByVersion(string viewUri, int BookId, int calendarDBVersion, out int currentDBVersion) { IntPtr recordList; @@ -344,8 +438,9 @@ namespace Tizen.Pims.Calendar /// /// The view URI to get records from /// - /// The count + /// The count of records /// + /// http://tizen.org/privilege/calendar.read public int GetCount(string viewUri) { int count = -1; @@ -363,8 +458,9 @@ namespace Tizen.Pims.Calendar /// /// The query used for filtering the results /// - /// The count + /// The count of records /// + /// http://tizen.org/privilege/calendar.read public int GetCount(CalendarQuery query) { int count = -1; @@ -382,6 +478,7 @@ namespace Tizen.Pims.Calendar /// /// The view URI of the record to subscribe for change notifications /// The callback function to register + /// http://tizen.org/privilege/calendar.read public void AddDBChangedDelegate(string viewUri, CalendarDBChangedDelegate callback) { Log.Debug(Globals.LogTag, "AddDBChangedDelegate"); @@ -405,6 +502,7 @@ namespace Tizen.Pims.Calendar /// /// The view URI of the record to subscribe for change notifications /// The callback function to register + /// http://tizen.org/privilege/calendar.read public void RemoveDBChangedDelegate(string viewUri, CalendarDBChangedDelegate callback) { Log.Debug(Globals.LogTag, "RemoveDBChangedDelegate"); @@ -424,6 +522,12 @@ namespace Tizen.Pims.Calendar /// /// The base record ID /// The record ID to link to + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public void LinkRecord(int baseId, int recordId) { Log.Debug(Globals.LogTag, "LinkRecord"); @@ -439,6 +543,12 @@ namespace Tizen.Pims.Calendar /// Unlink a record from base record. /// /// The record ID to unlink + /// http://tizen.org/privilege/calendar.write + /// Thrown when method failed due to invalid operation + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory + /// Thrown when application does not have proper privileges public void UnlinkRecord(int recordId) { Log.Debug(Globals.LogTag, "UnlinkRecord"); diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarErrorFactory.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarErrorFactory.cs index b2e4703..6918f88 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarErrorFactory.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarErrorFactory.cs @@ -22,24 +22,25 @@ namespace Tizen.Pims.Calendar internal enum CalendarError { None = Tizen.Internals.Errors.ErrorCode.None, /**< Successful */ - OutOfMemory = Tizen.Internals.Errors.ErrorCode.OutOfMemory, /**< Out of Memory */ - InvalidParameter = Tizen.Internals.Errors.ErrorCode.InvalidParameter, /**< Invalid parameter */ - FileNoSpace = Tizen.Internals.Errors.ErrorCode.FileNoSpaceOnDevice, /** -/// -/// -/// namespace Tizen.Pims.Calendar { /// + /// A filter includes the conditions for the search. /// public class CalendarFilter:IDisposable { internal IntPtr _filterHandle; /// - /// Creates a filter with string type. + /// Creates a filter with a condition for a string type. /// /// The view URI of a filter /// The property ID to add a condition /// The match flag /// The match value + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public CalendarFilter(string viewUri, uint propertyId, StringMatchType matchType, string matchValue) { int error = 0; @@ -55,12 +55,15 @@ namespace Tizen.Pims.Calendar } /// - /// Creates a filter with integer type. + /// Creates a filter with a condition for an integer type. /// /// The view URI of a filter /// The property ID to add a condition /// The match flag /// The match value + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public CalendarFilter(string viewUri, uint propertyId, IntegerMatchType matchType, int matchValue) { int error = 0; @@ -80,12 +83,15 @@ namespace Tizen.Pims.Calendar } /// - /// Creates a filter with long type. + /// Creates a filter with a condition for long type. /// /// The view URI of a filter /// The property ID to add a condition /// The match flag /// The match value + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public CalendarFilter(string viewUri, uint propertyId, IntegerMatchType matchType, long matchValue) { int error = 0; @@ -105,12 +111,15 @@ namespace Tizen.Pims.Calendar } /// - /// Creates a filter with double type. + /// Creates a filter with a condition for double type. /// /// The view URI of a filter /// The property ID to add a condition /// The match flag /// The match value + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public CalendarFilter(string viewUri, uint propertyId, IntegerMatchType matchType, double matchValue) { int error = 0; @@ -130,12 +139,15 @@ namespace Tizen.Pims.Calendar } /// - /// Creates a filter with CalendarTime type. + /// Creates a filter with a condition for CalendarTime type. /// /// The view URI of a filter /// The property ID to add a condition /// The match flag /// The match value + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public CalendarFilter(string viewUri, uint propertyId, IntegerMatchType matchType, CalendarTime matchValue) { int error = 0; @@ -263,6 +275,10 @@ namespace Tizen.Pims.Calendar } } + /// + /// Releases all resources used by the CalendarFilter. + /// It should be called after finished using of the object. + /// public void Dispose() { Dispose(true); @@ -270,12 +286,14 @@ namespace Tizen.Pims.Calendar #endregion /// - /// Adds a condition for the string type property. + /// Adds a condition for the string type. /// /// The operator type /// The property ID to add a condition /// The match flag /// The match valu + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid public void AddCondition(LogicalOperator logicalOperator, uint propertyId, StringMatchType matchType, string matchValue) { int error = Interop.Calendar.Filter.AddOperator(_filterHandle, logicalOperator); @@ -294,12 +312,14 @@ namespace Tizen.Pims.Calendar } /// - /// Adds a condition for the integer type property. + /// Adds a condition for the integer type. /// /// The operator type /// The property ID to add a condition /// The match flag /// The match valu + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid public void AddCondition(LogicalOperator logicalOperator, uint propertyId, IntegerMatchType matchType, int matchValue) { int error = Interop.Calendar.Filter.AddOperator(_filterHandle, logicalOperator); @@ -318,12 +338,14 @@ namespace Tizen.Pims.Calendar } /// - /// Adds a condition for the long type property. + /// Adds a condition for the long type. /// /// The operator type /// The property ID to add a condition /// The match flag /// The match valu + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid public void AddCondition(LogicalOperator logicalOperator, uint propertyId, IntegerMatchType matchType, long matchValue) { int error = Interop.Calendar.Filter.AddOperator(_filterHandle, logicalOperator); @@ -342,12 +364,14 @@ namespace Tizen.Pims.Calendar } /// - /// Adds a condition for the double type property. + /// Adds a condition for the double type. /// /// The operator type /// The property ID to add a condition /// The match flag /// The match valu + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid public void AddCondition(LogicalOperator logicalOperator, uint propertyId, IntegerMatchType matchType, double matchValue) { int error = Interop.Calendar.Filter.AddOperator(_filterHandle, logicalOperator); @@ -366,12 +390,14 @@ namespace Tizen.Pims.Calendar } /// - /// Adds a condition for the CalendarTime type property. + /// Adds a condition for the CalendarTime type. /// /// The operator type /// The property ID to add a condition /// The match flag /// The match valu + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid public void AddCondition(LogicalOperator logicalOperator, uint propertyId, IntegerMatchType matchType, CalendarTime matchValue) { int error = Interop.Calendar.Filter.AddOperator(_filterHandle, logicalOperator); @@ -395,6 +421,8 @@ namespace Tizen.Pims.Calendar /// /// The operator type /// The child filter + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid public void AddFilter(LogicalOperator logicalOperator, CalendarFilter filter) { int error = Interop.Calendar.Filter.AddOperator(_filterHandle, logicalOperator); diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarList.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarList.cs index 875d643..fdcf2a9 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarList.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarList.cs @@ -18,13 +18,10 @@ using System; using System.Collections; using System.Collections.Generic; -/// -/// -/// -/// namespace Tizen.Pims.Calendar { /// + /// A list of records with the same type. /// public class CalendarList:IDisposable { @@ -43,6 +40,8 @@ namespace Tizen.Pims.Calendar /// /// Creates a calendar list. /// + /// Thrown when an invoked method is not supported + /// Thrown when failed due to out of memory public CalendarList() { int error = Interop.Calendar.List.Create(out _listHandle); @@ -100,6 +99,10 @@ namespace Tizen.Pims.Calendar } } + /// + /// Releases all resources used by the CalendarList. + /// It should be called after finished using of the object. + /// public void Dispose() { Dispose(true); @@ -110,6 +113,8 @@ namespace Tizen.Pims.Calendar /// Adds a record to the calendar list. /// /// The record to be added + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid public void AddRecord(CalendarRecord record) { int error = Interop.Calendar.List.Add(_listHandle, record._recordHandle); @@ -127,6 +132,8 @@ namespace Tizen.Pims.Calendar /// Removes a record from the calendar list. /// /// The record to be removed + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid public void RemoveRecord(CalendarRecord record) { int error = Interop.Calendar.List.Remove(_listHandle, record._recordHandle); @@ -144,7 +151,7 @@ namespace Tizen.Pims.Calendar /// Retrieves a record from the calendar list. /// /// - /// CalendarRecord + /// calendar record /// public CalendarRecord GetCurrentRecord() { @@ -168,7 +175,9 @@ namespace Tizen.Pims.Calendar { int error = Interop.Calendar.List.Prev(_listHandle); if (CalendarError.None == (CalendarError)error) + { return true; + } else if (this.Count > 0 && CalendarError.NoData == (CalendarError)error) { Log.Debug(Globals.LogTag, "Nodata MovePrevious " + error); @@ -191,7 +200,9 @@ namespace Tizen.Pims.Calendar { int error = Interop.Calendar.List.Next(_listHandle); if (CalendarError.None == (CalendarError)error) + { return true; + } else if (this.Count > 0 && CalendarError.NoData == (CalendarError)error) { Log.Debug(Globals.LogTag, "Nodata MoveNext" + error); diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarManager.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarManager.cs index f2cbdfb..af6ef04 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarManager.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarManager.cs @@ -18,13 +18,10 @@ using System; using System.Collections.Generic; using static Interop.Calendar.Service; -/// -/// -/// -/// namespace Tizen.Pims.Calendar { /// + /// A class for managing calendar information. It allows applications to use calendar service. /// public class CalendarManager : IDisposable { @@ -33,6 +30,7 @@ namespace Tizen.Pims.Calendar /// /// Create a manager. /// + /// Thrown when method failed due to invalid operation public CalendarManager() { int error = Interop.Calendar.Service.Connect(); @@ -50,7 +48,8 @@ namespace Tizen.Pims.Calendar } #region IDisposable Support - private bool disposedValue = false; // To detect redundant calls + /// To detect redundant calls + private bool disposedValue = false; protected virtual void Dispose(bool disposing) { @@ -68,6 +67,10 @@ namespace Tizen.Pims.Calendar } } + /// + /// Releases all resources used by the CalendarManager. + /// It should be called after finished using of the object. + /// public void Dispose() { Dispose(true); diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarQuery.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarQuery.cs index ddd9c02..941699a 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarQuery.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarQuery.cs @@ -17,14 +17,16 @@ using System; using static Interop.Calendar.Query; -/// -/// -/// -/// namespace Tizen.Pims.Calendar { - /// + /// A query is used to retrieve data which satisfies given criteria. /// + /// + /// A query is used to retrieve calendar data which satisfies a given criteria, + /// such as an integer property being greater than a given value, + /// or a string property containing a given substring. + /// A query needs a filter which can set the conditions for the search. + /// public class CalendarQuery : IDisposable { internal IntPtr _queryHandle; @@ -33,6 +35,9 @@ namespace Tizen.Pims.Calendar /// Creates a query. /// /// The view URI of a query + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public CalendarQuery(string viewUri) { int error = Interop.Calendar.Query.Create(viewUri, out _queryHandle); @@ -72,6 +77,10 @@ namespace Tizen.Pims.Calendar } } + /// + /// Releases all resources used by the CalendarQuery. + /// It should be called after finished using of the object. + /// public void Dispose() { Dispose(true); @@ -82,6 +91,7 @@ namespace Tizen.Pims.Calendar /// Adds property IDs for projection. /// /// The property ID array + /// Thrown when one of the arguments provided to a method is not valid public void SetProjection(uint[] propertyIdArray) { int error = Interop.Calendar.Query.SetProjection(_queryHandle, propertyIdArray, propertyIdArray.Length); @@ -96,6 +106,7 @@ namespace Tizen.Pims.Calendar /// Sets the "distinct" option for projection. /// /// If true it is set, otherwise if false it is unset + /// Thrown when one of the arguments provided to a method is not valid public void SetDistinct(bool set) { int error = Interop.Calendar.Query.SetDistinct(_queryHandle, set); @@ -110,6 +121,7 @@ namespace Tizen.Pims.Calendar /// Sets the filter for a query. /// /// The filter + /// Thrown when one of the arguments provided to a method is not valid public void SetFilter(CalendarFilter filter) { int error = Interop.Calendar.Query.SetFilter(_queryHandle, filter._filterHandle); @@ -125,6 +137,7 @@ namespace Tizen.Pims.Calendar /// /// The property ID to sort /// If true it sorts in the ascending order, otherwise if false it sorts in the descending order + /// Thrown when one of the arguments provided to a method is not valid public void SetSort(uint propertyId, bool isAscending) { int error = Interop.Calendar.Query.SetSort(_queryHandle, propertyId, isAscending); diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarRecord.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarRecord.cs index 9c31306..a6b25d0 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarRecord.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarRecord.cs @@ -18,14 +18,20 @@ using System; using System.Collections.Generic; using System.Runtime.InteropServices; -/// -/// -/// -/// namespace Tizen.Pims.Calendar { /// + /// A record represents an actual record in the database /// + /// + /// A record represents an actual record in the database, + /// but you can also consider it a piece of information, such as an alarm, attendee and extended. + /// A record can be a complex set of data, containing other data. + /// For example, a calendar record contains the alarm property, which is a reference to an alarm record. + /// An alarm record could belong to a event record, + /// and its alarm id property is set to the identifier of the corresponding event. + /// In this case, the alarm is the child record of the event and the event is the parent record. + /// public class CalendarRecord : IDisposable { internal string _uri; @@ -85,6 +91,9 @@ namespace Tizen.Pims.Calendar /// Creates a record. /// /// The view URI + /// Thrown when an invoked method is not supported + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public CalendarRecord(string viewUri) { int error = 0; @@ -104,7 +113,8 @@ namespace Tizen.Pims.Calendar } #region IDisposable Support - internal bool _disposedValue = false; // To detect redundant calls + /// To detect redundant calls + internal bool _disposedValue = false; protected virtual void Dispose(bool disposing) { @@ -123,6 +133,10 @@ namespace Tizen.Pims.Calendar } } + /// + /// Releases all resources used by the CalendarRecord. + /// It should be called after finished using of the object. + /// public void Dispose() { Dispose(true); @@ -167,6 +181,10 @@ namespace Tizen.Pims.Calendar /// /// Makes a clone of a record. /// + /// + /// A cloned record + /// + /// Thrown when failed due to out of memory public CalendarRecord Clone() { IntPtr _clonedRecordHandle; @@ -195,8 +213,9 @@ namespace Tizen.Pims.Calendar /// /// The property ID /// - /// The value of record which property id is matched. + /// The value of the property corresponding to property id. /// + /// Thrown when one of the arguments provided to a method is not valid public T Get(uint propertyId) { object parsedValue = null; @@ -265,10 +284,11 @@ namespace Tizen.Pims.Calendar } /// - /// Sets a object to a record. + /// Sets a value of the property to a record. /// /// The property ID /// value + /// Thrown when one of the arguments provided to a method is not valid public void Set(uint propertyId, T value) { if (typeof(T) == typeof(string)) @@ -334,6 +354,7 @@ namespace Tizen.Pims.Calendar /// /// The property ID /// The child record + /// Thrown when one of the arguments provided to a method is not valid public void AddChildRecord(uint propertyId, CalendarRecord childRecord) { int error = Interop.Calendar.Record.AddChildRecord(_recordHandle, propertyId, childRecord._recordHandle); @@ -350,6 +371,7 @@ namespace Tizen.Pims.Calendar /// /// The property ID /// The child record + /// Thrown when one of the arguments provided to a method is not valid public void RemoveChildRecord(uint propertyId, CalendarRecord childRecord) { int error = Interop.Calendar.Record.RemoveChildRecord(_recordHandle, propertyId, childRecord._recordHandle); @@ -362,12 +384,13 @@ namespace Tizen.Pims.Calendar } /// - /// Get a child record count. + /// Gets a child record from the parent record /// /// The property ID /// - /// Count + /// The number of child records corresponding to property ID /// + /// Thrown when one of the arguments provided to a method is not valid public int GetChildRecordCount(uint propertyId) { int count = 0; @@ -381,13 +404,14 @@ namespace Tizen.Pims.Calendar } /// - /// Get a child record with index. + /// Gets a child record from the parent record /// /// The property ID /// The child record index /// - /// CalendarRecord + /// The record /// + /// Thrown when one of the arguments provided to a method is not valid public CalendarRecord GetChildRecord(uint propertyId, int index) { IntPtr handle; @@ -402,12 +426,13 @@ namespace Tizen.Pims.Calendar } /// - /// Makes a clone of a given record's child record list. + /// Clones a child record list corresponding to property ID /// /// The property ID /// - /// CalendarList + /// the record list /// + /// Thrown when one of the arguments provided to a method is not valid public CalendarList CloneChildRecordList(uint propertyId) { IntPtr listHandle; diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarReminder.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarReminder.cs index 3de7e19..f1193ef 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarReminder.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarReminder.cs @@ -17,14 +17,14 @@ using System; using static Interop.Calendar.Reminder; -/// -/// -/// -/// namespace Tizen.Pims.Calendar { /// + /// A class for reminder for event. /// + /// + /// The client who wants to be alerted at specific time should register MIME("application/x-tizen.calendar.reminder") type in manifest.xml file. + /// public class CalendarReminder : IDisposable { #region IDisposable Support @@ -42,6 +42,10 @@ namespace Tizen.Pims.Calendar } } + /// + /// Releases all resources used by the CalendarReminder. + /// It should be called after finished using of the object. + /// public void Dispose() { Dispose(true); @@ -85,12 +89,12 @@ namespace Tizen.Pims.Calendar if (s_reminderAlerted == null) { /// _reminderAlertedCallback is removed by .Net Core - /// int error = Interop.Calendar.Reminder.Remove(_reminderAlertedCallback, IntPtr.Zero); - /// if (CalendarError.None != (CalendarError)error) - /// { - /// Log.Error(Globals.LogTag, "Remove reminder Failed with error " + error); - /// throw CalendarErrorFactory.GetException(error); - /// } + int error = Interop.Calendar.Reminder.Remove(_reminderAlertedCallback, IntPtr.Zero); + if (CalendarError.None != (CalendarError)error) + { + Log.Error(Globals.LogTag, "Remove reminder Failed with error " + error); + throw CalendarErrorFactory.GetException(error); + } } } } diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarStructs.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarStructs.cs index f3d9821..3ac883c 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarStructs.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarStructs.cs @@ -17,13 +17,10 @@ using System; using System.Runtime.InteropServices; -/// -/// -/// -/// namespace Tizen.Pims.Calendar { /// + /// A class for time to set, get or calcurate. /// public class CalendarTime : IComparable { @@ -65,6 +62,8 @@ namespace Tizen.Pims.Calendar /// hour /// minute /// second + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public CalendarTime(int year, int month, int day, int hour, int minute, int second) { _type = (int)Type.Local; @@ -94,10 +93,15 @@ namespace Tizen.Pims.Calendar /// /// A 32-bit signed integer that indicates the relative order of the objects being compared. /// + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public int CompareTo(CalendarTime t) { if (_type != t._type) - throw new NotImplementedException("Not to compare with different type"); + { + Log.Error(Globals.LogTag, "Not to compare with different type"); + throw CalendarErrorFactory.GetException((int)CalendarError.InvalidParameter); + } if (_type == (int)Type.Utc) return UtcTime.CompareTo(t.UtcTime); diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarVcalendar.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarVcalendar.cs index 9b40aeb..1a7a3a8 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarVcalendar.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarVcalendar.cs @@ -18,14 +18,14 @@ using System; using System.Collections.Generic; using System.Threading.Tasks; -/// -/// -/// -/// namespace Tizen.Pims.Calendar { /// + /// A class for parsing and composing vCalendar. /// + /// + /// It's based on the vCalendar v2.0 specification + /// public class CalendarVcalendar { internal CalendarVcalendar() @@ -41,6 +41,8 @@ namespace Tizen.Pims.Calendar /// /// The composed stream. /// + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public static string Compose(CalendarList list) { string stream; @@ -58,8 +60,10 @@ namespace Tizen.Pims.Calendar /// /// The vcalendar stream /// - /// List of records + /// the record list /// + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public static CalendarList Parse(string stream) { int error = 0; @@ -77,7 +81,10 @@ namespace Tizen.Pims.Calendar /// Parse vcalendar file with foreach /// /// The file path of the vCalendar stream file - /// + /// he callback function to invoke + /// Thrown when method failed due to invalid operation + /// Thrown when one of the arguments provided to a method is not valid + /// Thrown when failed due to out of memory public static void ParseForEach(string path, ParseDelegate callback) { int error = 0; diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarViews.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarViews.cs index 49a85f4..b4ddd17 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarViews.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/CalendarViews.cs @@ -18,14 +18,15 @@ using System; using System.Collections; using System.Collections.Generic; -/// -/// -/// -/// namespace Tizen.Pims.Calendar { /// + /// This class provides information about views with properties. /// + /// + /// A view is a class which describes properties of a record. + /// A record can have basic properties of five types: integer, string, long, double, CalendarTime. + /// public static class CalendarViews { /// data type mask 0x0FF00000 @@ -330,16 +331,11 @@ namespace Tizen.Pims.Calendar ExtendedValue = (ViewExtended|DataTypeString) + 4, } - internal const uint AverageSizeOfRecord = 56; ///average size + ///average size + internal const uint AverageSizeOfRecord = 56; - /// - /// - public class Book + public static class Book { - internal Book() - { - } - /// /// Identifier of this calendar book view /// @@ -406,14 +402,8 @@ namespace Tizen.Pims.Calendar public const uint Mode = (uint)PropertyIds.BookMode; } - /// - /// - public class Event + public static class Event { - internal Event() - { - } - /// /// Identifier of this event view /// @@ -656,15 +646,8 @@ namespace Tizen.Pims.Calendar public const uint LinkBaseId = (uint)PropertyIds.EventLinkBaseId; } - /// - /// - /// - public class Todo + public static class Todo { - internal Todo() - { - } - /// /// Identifier of this todo view /// @@ -863,15 +846,8 @@ namespace Tizen.Pims.Calendar public const uint IsAllday = (uint)PropertyIds.TodoIsAllday; } - /// - /// - /// - public class Timezone + public static class Timezone { - internal Timezone() - { - } - /// /// Identifier of this timezone view /// @@ -938,14 +914,8 @@ namespace Tizen.Pims.Calendar public const uint CalendarId = (uint)PropertyIds.TimezoneCalendarId; } - /// - /// - public class Attendee + public static class Attendee { - internal Attendee() - { - } - /// /// Identifier of this calendar attendee view /// @@ -1008,14 +978,8 @@ namespace Tizen.Pims.Calendar public const uint ParentId = (uint)PropertyIds.AttendeeParentId; } - /// - /// - public class Alarm + public static class Alarm { - internal Alarm() - { - } - /// /// Identifier of this calendar alarm view /// @@ -1054,14 +1018,8 @@ namespace Tizen.Pims.Calendar public const uint AlarmTime = (uint)PropertyIds.AlarmAlarm; } - /// - /// - public class InstanceUtimeBook + public static class InstanceUtimeBook { - internal InstanceUtimeBook() - { - } - /// /// Identifier of this instance utime book /// @@ -1140,14 +1098,8 @@ namespace Tizen.Pims.Calendar public const uint SyncData1 = (uint)PropertyIds.InstanceUtimeBookSyncData1; } - /// - /// - public class InstanceLocaltimeBook + public static class InstanceLocaltimeBook { - internal InstanceLocaltimeBook() - { - } - /// /// Uri /// @@ -1230,15 +1182,8 @@ namespace Tizen.Pims.Calendar public const uint IsAllday = (uint)PropertyIds.InstanceLocaltimeBookIsAllday; } - /// - /// - /// - public class InstanceUtimeBookExtended + public static class InstanceUtimeBookExtended { - internal InstanceUtimeBookExtended() - { - } - /// /// Uri /// @@ -1341,15 +1286,8 @@ namespace Tizen.Pims.Calendar public const uint SyncData4 = (uint)PropertyIds.InstanceUtimeBookExtendedSyncData4; } - /// - /// - /// - public class InstanceLocaltimeBookExtended + public static class InstanceLocaltimeBookExtended { - internal InstanceLocaltimeBookExtended() - { - } - /// /// Uri /// @@ -1454,14 +1392,8 @@ namespace Tizen.Pims.Calendar public const uint IsAllday = (uint)PropertyIds.InstanceLocaltimeBookExtendedIsAllday; } - /// - /// - public class UpdatedInfo + public static class UpdatedInfo { - internal UpdatedInfo() - { - } - /// /// Identifier of this updatedInfo view /// @@ -1484,14 +1416,8 @@ namespace Tizen.Pims.Calendar public const uint Version = (uint)PropertyIds.UpdateInfoVersion; } - /// - /// - public class Extended + public static class Extended { - internal Extended() - { - } - /// /// Identifier of this extended_property view /// diff --git a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/ReminderEventArgs.cs b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/ReminderEventArgs.cs index 11bb9d4..5d4cd07 100644 --- a/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/ReminderEventArgs.cs +++ b/src/Tizen.Pims.Calendar/Tizen.Pims.Calendar/ReminderEventArgs.cs @@ -17,10 +17,6 @@ using System; using System.Collections.Generic; -/// -/// -/// -/// namespace Tizen.Pims.Calendar { /// -- 2.7.4