From ad362668ed1b6daa900bdf25ecb7b73d9b7d8604 Mon Sep 17 00:00:00 2001 From: Miles Lott Date: Fri, 14 Sep 2001 20:21:06 +0000 Subject: [PATCH] add unfinished services proposal --- phpgwapi/doc/xmlrpc/gw_interface.dvi | Bin 0 -> 15964 bytes phpgwapi/doc/xmlrpc/gw_interface.lyx | 403 ++++++++++++++++++++++++++ phpgwapi/doc/xmlrpc/gw_interface.lyx~ | 395 +++++++++++++++++++++++++ phpgwapi/doc/xmlrpc/gw_interface.pdf | Bin 0 -> 12490 bytes phpgwapi/doc/xmlrpc/gw_interface.sgml | 394 +++++++++++++++++++++++++ phpgwapi/doc/xmlrpc/gw_interface.txt | 277 ++++++++++++++++++ 6 files changed, 1469 insertions(+) create mode 100644 phpgwapi/doc/xmlrpc/gw_interface.dvi create mode 100644 phpgwapi/doc/xmlrpc/gw_interface.lyx create mode 100644 phpgwapi/doc/xmlrpc/gw_interface.lyx~ create mode 100644 phpgwapi/doc/xmlrpc/gw_interface.pdf create mode 100644 phpgwapi/doc/xmlrpc/gw_interface.sgml create mode 100644 phpgwapi/doc/xmlrpc/gw_interface.txt diff --git a/phpgwapi/doc/xmlrpc/gw_interface.dvi b/phpgwapi/doc/xmlrpc/gw_interface.dvi new file mode 100644 index 0000000000000000000000000000000000000000..90a51f9614243217aefcdbe97ca9c2b40e851d34 GIT binary patch literal 15964 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 AG5`Po literal 0 HcmV?d00001 diff --git a/phpgwapi/doc/xmlrpc/gw_interface.lyx b/phpgwapi/doc/xmlrpc/gw_interface.lyx new file mode 100644 index 0000000000..928120cf57 --- /dev/null +++ b/phpgwapi/doc/xmlrpc/gw_interface.lyx @@ -0,0 +1,403 @@ +#LyX 1.1 created this file. For more info see http://www.lyx.org/ +\lyxformat 218 +\textclass docbook +\language english +\inputencoding auto +\fontscheme default +\graphics default +\paperfontsize default +\spacing single +\papersize Default +\paperpackage a4 +\use_geometry 0 +\use_amsmath 0 +\paperorientation portrait +\secnumdepth 3 +\tocdepth 3 +\paragraph_separation indent +\defskip medskip +\quotes_language english +\quotes_times 2 +\papercolumns 1 +\papersides 1 +\paperpagestyle default + +\layout Title + +Proposal for a Common Groupware Interface Standard +\layout Author + +by Miles Lott +\layout Date + +September 13, 2001 +\layout Standard + + +\begin_inset LatexCommand \tableofcontents{} + +\end_inset + + +\layout Section + +Scope +\layout Standard + +As many different opensource and freesoftware groupware systems are being + developed, the full realization of the dream of a connected world should + be prefaced by an agreement to interoperate. + There are limited ways in which cooperation with these and commercial groupware + systems may be achecived, the majority if not all of which were derived + via the establishment of open standards. + These might include email (POP3/IMAP), contacts(LDAP,vcard), or scheduling(ical +/vcal). + It is felt that while these have proven themselves to be very useful, they + are insufficient to satisfy the real needs of a typical business environment. +\layout Standard + +This document hopes to provide a reasonable, if limited, recommendation + for a set of standardized methods to be used for groupware services interaction. + More specifically, it hopes to address the need for such a standard as + well as to spur discussion about the common service names and methods themselve +s. +\layout Standard + +Examples will be given for implementations in XML-RPC, since this standard + is relatively fixed and open. +\layout Standard + +This document does not provide recommendations for the underlying access + control system which would allow or deny a particular action. +\layout Standard + +Also not discussed here is login and authorization to be used for initial + access to a service provider. +\layout Section + +The Services +\layout Subsection + +Overview +\layout Standard + +There are a few common services types that will be needed for minimum useability + of a groupware server or application. + They are: +\layout Itemize + +Contacts +\layout Itemize + +Schedule +\layout Itemize + +Notes +\layout Itemize + +Todo +\layout Standard + +These services are represented already in places such as existing groupware + client-server applications and also in the PalmOS basic-4 buttons and applicati +ons. + Different systems may have different names for these services internally, + e.g. + Contacts - addresses, addressbook, people, Schedule - calendar, agenda, + meetings. +\layout Standard + +Within each of these services are some common methods that would be called + to store, retreive, or update data: +\layout Itemize + +read_list +\layout Itemize + +read +\layout Itemize + +save +\layout Itemize + +delete +\layout Subsection + +Detail +\layout Subsubsection + +Contacts +\layout Standard + +The concept of contacts may encompass local addressbooks, LDAP, and lists + stored in other media. + The purpose of the contacts service is not to duplicate or attempt to replace + these. + In some respects, it might do just that. + But its goal is more so to provide a common and shareable way for the other + core services to create, edit, and read a common user and address list. + All of the other services may use the contact service to obtain record + owner information to be used in access control. + They would also use them when it is required to share this data, as with + a meeting where other local and non-local users will be invited to attend. +\layout Standard + +Contacts may include the local installed user base, users on other cooperative + servers, or email addresses used for limited cooperation with other groupware + services that are not compliant with this service scheme or implementations + thereof. + It could also include individuals using web-based or local ISP email services. + The scope of this document, however, is to define the service with regard + to the common methods to be used for server-server and client-server communicat +ions: +\layout Itemize + +read_list +\layout Standard + +This method is used to list contacts, with or without limits, filters, or + search criteria. + In this way it can be used for simple lists or to search for contact records + and their identifiers. + The optional search criteria includes: +\layout Enumerate + +start - Start at this identifier (integer: default 0) +\layout Enumerate + +limit - Limit to this number of records returned(integer: unlimited by default) +\layout Enumerate + +fieldlist - limit to showing only these fields (array: default to identifier, + owner identifier, possibly firstname and lastname) +\layout Enumerate + +filter - Show records that are public or private only, or other system-specific + filters, e.g group or company(string: default '') +\layout Enumerate + +query - Search internal fieldlist for a value (string: default '') +\layout Standard + +The return for this method includes: +\layout Enumerate + +count of number of records returned(integer) +\layout Enumerate + +array consisting of: array: identifier => (array: fieldlist key => value + pairs) +\layout Itemize + +read +\layout Standard + +Once the identifier for a single contact record is known, the contact may + be read for more detail using this method. + This takes two parameters: +\layout Enumerate + +identifier - (integer: no default) +\layout Enumerate + +fieldlist - limit to showing only these fields (array: default to identifier, + owner identifier, possibly firstname and lastname) +\layout Standard + +And returns: +\layout Enumerate + +array consisting of: array: identifier => (array: fieldlist key => value + pairs) +\layout Itemize + +save +\layout Standard + +This is a method used to save an existing record or create a new one. + If the identifier for an existing record is not passed, a new entry will + be created. +\layout Itemize + +delete +\layout Standard + +This will allow deletion of a record by passing its identifier. +\layout Subsubsection + +Schedule +\layout Subsubsection + +Notes +\layout Subsubsection + +Todo +\layout Subsection + +Examples in XML-RPC +\layout Standard + +Query the contacts service for read_list, using only start and limit to + grab the first 5 records, starting with identifier 1. + Additionally, return only the firstname and lastname fields n_given and + n_family (firstname and lastname in pseudo vcard format): +\layout Code + + +\layout Code + +service.contacts.read_list +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + +start +\layout Code + +1 +\layout Code + + +\layout Code + +limit +\layout Code + +5 +\layout Code + + +\layout Code + +fields +\layout Code + + +\layout Code + +n_given +\layout Code + +n_given +\layout Code + + +\layout Code + +n_family +\layout Code + +n_family +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + +query +\layout Code + + +\layout Code + + +\layout Code + +filter +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + + +\layout Section + +Conclusion +\layout Standard + +This document outlined the following services and methods: +\layout Subsection + +Contacts: +\layout Itemize + +service.contacts.read_list([search criteria]) +\layout Itemize + +service.contacts.read(identifier,[fieldlist]) +\layout Itemize + +service.contacts.save(fields) +\layout Itemize + +service.contacts.delete(identifier) +\layout Subsection + +Schedule: +\layout Itemize + +service.schedule.read_list([search criteria]) +\layout Itemize + +service.schedule.read(identifier,[fieldlist]) +\layout Itemize + +service.schedule.save(fields) +\layout Itemize + +service.schedule.delete(identifier) +\layout Subsection + +Notes: +\layout Itemize + +service.notes.read_list([search criteria]) +\layout Itemize + +service.notes.read(identifier,[fieldlist]) +\layout Itemize + +service.notes.save(fields) +\layout Itemize + +service.notes.delete(identifier) +\layout Subsection + +Todo: +\layout Itemize + +service.todo.read_list(search criteria) +\layout Itemize + +service.todo.read(identifer,[fieldlist]) +\layout Itemize + +service.todo.save(fields) +\layout Itemize + +service.todo.delete(identifier) +\the_end diff --git a/phpgwapi/doc/xmlrpc/gw_interface.lyx~ b/phpgwapi/doc/xmlrpc/gw_interface.lyx~ new file mode 100644 index 0000000000..7370e43589 --- /dev/null +++ b/phpgwapi/doc/xmlrpc/gw_interface.lyx~ @@ -0,0 +1,395 @@ +#LyX 1.1 created this file. For more info see http://www.lyx.org/ +\lyxformat 218 +\textclass docbook +\language english +\inputencoding auto +\fontscheme default +\graphics default +\paperfontsize default +\spacing single +\papersize Default +\paperpackage a4 +\use_geometry 0 +\use_amsmath 0 +\paperorientation portrait +\secnumdepth 3 +\tocdepth 3 +\paragraph_separation indent +\defskip medskip +\quotes_language english +\quotes_times 2 +\papercolumns 1 +\papersides 1 +\paperpagestyle default + +\layout Title + +Proposal for a Common Groupware Interface Standard +\layout Author + +by Miles Lott +\layout Date + +September 13, 2001 +\layout Section + +Scope +\layout Standard + +As many different opensource and freesoftware groupware systems are being + developed, the full realization of the dream of a connected world should + be prefaced by an agreement to interoperate. + There are limited ways in which cooperation with these and commercial groupware + systems may be achecived, the majority if not all of which were derived + via the establishment of open standards. + These might include email (POP3/IMAP), contacts(LDAP,vcard), or scheduling(ical +/vcal). + It is felt that while these have proven themselves to be very useful, they + are insufficient to satisfy the real needs of a typical business environment. +\layout Standard + +This document hopes to provide a reasonable, if limited, recommendation + for a set of standardized methods to be used for groupware services interaction. + More specifically, it hopes to address the need for such a standard as + well as to spur discussion about the common service names and methods themselve +s. +\layout Standard + +Examples will be given for implementations in XML-RPC, since this standard + is relatively fixed and open. +\layout Standard + +This document does not provide recommendations for the underlying access + control system which would allow or deny a particular action. +\layout Standard + +Also not discussed here is login and authorization to be used for initial + access to a service provider. +\layout Section + +The Services +\layout Subsection + +Overview +\layout Standard + +There are a few common services types that will be needed for minimum useability + of a groupware server or application. + They are: +\layout Itemize + +Contacts +\layout Itemize + +Schedule +\layout Itemize + +Notes +\layout Itemize + +Todo +\layout Standard + +These services are represented already in places such as existing groupware + client-server applications and also in the PalmOS basic-4 buttons and applicati +ons. + Different systems may have different names for these services internally, + e.g. + Contacts - addresses, addressbook, people, Schedule - calendar, agenda, + meetings. +\layout Standard + +Within each of these services are some common methods that would be called + to store, retreive, or update data: +\layout Itemize + +read_list +\layout Itemize + +read +\layout Itemize + +save +\layout Itemize + +delete +\layout Subsection + +Detail +\layout Subsubsection + +Contacts +\layout Standard + +The concept of contacts may encompass local addressbooks, LDAP, and lists + stored in other media. + The purpose of the contacts service is not to duplicate or attempt to replace + these. + In some respects, it might do just that. + But its goal is more so to provide a common and shareable way for the other + core services to create, edit, and read a common user and address list. + All of the other services may use the contact service to obtain record + owner information to be used in access control. + They would also use them when it is required to share this data, as with + a meeting where other local and non-local users will be invited to attend. +\layout Standard + +Contacts may include the local installed user base, users on other cooperative + servers, or email addresses used for limited cooperation with other groupware + services that are not compliant with this service scheme or implementations + thereof. + It could also include individuals using web-based or local ISP email services. + The scope of this document, however, is to define the service with regard + to the common methods to be used for server-server and client-server communicat +ions: +\layout Itemize + +read_list +\layout Standard + +This method is used to list contacts, with or without limits, filters, or + search criteria. + In this way it can be used for simple lists or to search for contact records + and their identifiers. + The optional search criteria includes: +\layout Enumerate + +start - Start at this identifier (integer: default 0) +\layout Enumerate + +limit - Limit to this number of records returned(integer: unlimited by default) +\layout Enumerate + +fieldlist - limit to showing only these fields (array: default to identifier, + owner identifier, possibly firstname and lastname) +\layout Enumerate + +filter - Show records that are public or private only, or other system-specific + filters, e.g group or company(string: default '') +\layout Enumerate + +query - Search internal fieldlist for a value (string: default '') +\layout Standard + +The return for this method includes: +\layout Enumerate + +count of number of records returned(integer) +\layout Enumerate + +array consisting of: array: identifier => (array: fieldlist key => value + pairs) +\layout Itemize + +read +\layout Standard + +Once the identifier for a single contact record is known, the contact may + be read for more detail using this method. + This takes two parameters: +\layout Enumerate + +identifier - (integer: no default) +\layout Enumerate + +fieldlist - limit to showing only these fields (array: default to identifier, + owner identifier, possibly firstname and lastname) +\layout Standard + +And returns: +\layout Enumerate + +array consisting of: array: identifier => (array: fieldlist key => value + pairs) +\layout Itemize + +save +\layout Standard + +This is a method used to save an existing record or create a new one. + If the identifier for an existing record is not passed, a new entry will + be created. +\layout Itemize + +delete +\layout Standard + +This will allow deletion of a record by passing its identifier. +\layout Subsubsection + +Schedule +\layout Subsubsection + +Notes +\layout Subsubsection + +Todo +\layout Subsection + +Examples in XML-RPC +\layout Standard + +Query the contacts service for read_list, using only start and limit to + grab the first 5 records, starting with identifier 1. + Additionally, return only the firstname and lastname fields n_given and + n_family (firstname and lastname in pseudo vcard format): +\layout Code + + +\layout Code + +service.contacts.read_list +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + +start +\layout Code + +1 +\layout Code + + +\layout Code + +limit +\layout Code + +5 +\layout Code + + +\layout Code + +fields +\layout Code + + +\layout Code + +n_given +\layout Code + +n_given +\layout Code + + +\layout Code + +n_family +\layout Code + +n_family +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + +query +\layout Code + + +\layout Code + + +\layout Code + +filter +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + + +\layout Code + + +\layout Section + +Conclusion +\layout Standard + +This document outlined the following services and methods: +\layout Subsection + +Contacts: +\layout Itemize + +service.contacts.read_list([search criteria]) +\layout Itemize + +service.contacts.read(identifier,[fieldlist]) +\layout Itemize + +service.contacts.save(fields) +\layout Itemize + +service.contacts.delete(identifier) +\layout Subsection + +Schedule: +\layout Itemize + +service.schedule.read_list([search criteria]) +\layout Itemize + +service.schedule.read(identifier,[fieldlist]) +\layout Itemize + +service.schedule.save(fields) +\layout Itemize + +service.schedule.delete(identifier) +\layout Subsection + +Notes: +\layout Itemize + +service.notes.read_list([search criteria]) +\layout Itemize + +service.notes.read(identifier,[fieldlist]) +\layout Itemize + +service.notes.save(fields) +\layout Itemize + +service.notes.delete(identifier) +\layout Subsection + +Todo: +\layout Itemize + +service.todo.read_list(search criteria) +\layout Itemize + +service.todo.read(identifer,[fieldlist]) +\layout Itemize + +service.todo.save(fields) +\layout Itemize + +service.todo.delete(identifier) +\the_end diff --git a/phpgwapi/doc/xmlrpc/gw_interface.pdf b/phpgwapi/doc/xmlrpc/gw_interface.pdf new file mode 100644 index 0000000000000000000000000000000000000000..a9e7da2e073fc97616a52d2e29093234c3d934d1 GIT binary patch literal 12490 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 F_#dPJplAR9 literal 0 HcmV?d00001 diff --git a/phpgwapi/doc/xmlrpc/gw_interface.sgml b/phpgwapi/doc/xmlrpc/gw_interface.sgml new file mode 100644 index 0000000000..f70102f89e --- /dev/null +++ b/phpgwapi/doc/xmlrpc/gw_interface.sgml @@ -0,0 +1,394 @@ + + +
+ + + + Common Groupware Interface Standard + + + + + Scope + + + As many different opensource and freesoftware groupware systems are being developed, the full realization of the dream of a connected world must be prefaced by an agreement to interoperate. There are limited ways in which cooperation with commercial groupware systems may be achecived, the majority if not all of which were derived via the establishment of open standards. These might include email (POP3/IMAP), contacts(LDAP,vcard), or scheduling(ical/vcal). It is felt that while these have proven themselves to be very useful, they are insufficient to satisfy the real needs of a typical corporate environment. + + + This document hopes to provide a reasonable recommendation for a set of standardized methods to be used for groupware services interaction. More specifically, it hopes to address the need for such a standard as well as to spur discussion about the common service names and methods themselves. + + + Examples will be given for implementations in XML-RPC, since this standard is relatively fixed and open. + + + This document does not provide recommendations for the underlying access control system which would allow or deny a particular action. + + + Also not discussed here is login and authorization to be used for initial access to a service provider. + + + + + The Services + + + + Overview + + + There are a few common services types that will be needed for minimum useability of a groupware server or application. They are: + + + + + Contacts + + + + + Schedule + + + + + Notes + + + + + Todo + + + + + These services are represented already in places such as existing groupware client-server applications and also in the PalmOS basic-4 buttons and applications. + + + Within each of these services are some common methods that would be called to store, retreive, or update data: + + + + + read_list + + + + + read + + + + + save + + + + + delete + + + + + + + Detail + + + + Contacts + + + The concept of contacts may encompass local addressbooks, LDAP, and lists stored in other media. The purpose of the contacts service is not to duplicate or attempt to replace these. In some respects, it might do just that. But its goal is more so to provide a common and shareable way for the other core services to create, edit, and read a common user and address list. All of the other services may use the contact service to obtain record owner information to be used in access control. They would also use them when it is required to share this data, as with a meeting where other local and non-local users will be invited to attend. + + + Contacts may include the local installed user base, users on other cooperative servers, or email addresses used for limited cooperation with other groupware services that are not compliant with this service scheme or implementations thereof. It could also include individuals using web-based or local ISP email services. The scope of this document, however, is to define the service with regard to the common methods to be used: + + + + + read_list + + + + + This method is used to list contacts, with or without limits, filters, or search criteria. In this way it can be used for simple lists or to search for contact records and their identifiers. The optional search criteria includes: + + + + + start - Start at this identifier (integer: default 0) + + + + + limit - Limit to this number of records returned(integer: unlimited by default) + + + + + fieldlist - limit to showing only these fields (array: default to identifier, owner identifier, possibly firstname and lastname) + + + + + filter - Show records that are public or private only, or other system-specific filters, e.g group or company(string: default '') + + + + + query - Search internal fieldlist for a value (string: default '') + + + + + The return for this method includes: + + + + + count of number of records returned(integer) + + + + + array consisting of: array: identifier => (array: fieldlist key => value pairs) + + + + + + + read + + + + + Once the identifier for a single contact record is known, the contact may be read for more detail using this method. This takes two parameters: + + + + + identifier - (integer: no default) + + + + + fieldlist - limit to showing only these fields (array: default to identifier, owner identifier, possibly firstname and lastname) + + + + + And returns: + + + + + array consisting of: array: identifier => (array: fieldlist key => value pairs) + + + + + + + save + + + + + This is a method used to save an existing record or create a new one. If the identifier for an existing record is not passed, a new entry will be created. + + + + + delete + + + + + This will allow deletion of a record by passing its identifier. + + + + + Schedule + + + + + Notes + + + + + Todo + + + + + + Examples in XML-RPC + + + Query the contacts service for read_list, using only start and limit to grab the first 5 records, starting with identifier 1. Additionally, return only the firstname and lastname fields n_given and n_family (firstname and lastname in pseudo vcard format): + + + +]]>service.contacts.read_list +]]> +]]> +]]> +]]>start +]]>1 +]]> +]]>limit +]]>5 +]]> +]]>fields +]]> +]]>n_given +]]>n_given +]]> +]]>n_family +]]>n_family +]]> +]]> +]]> +]]>query +]]> +]]> +]]>filter +]]> +]]> +]]>sort +]]> +]]> +]]>order +]]> +]]> +]]> +]]> +]]> +]]> +]]> + + + + + Conclusion + + + This document outlined the following services and methods: + + + + Contacts: + + + + + service.contacts.read_list([search criteria]) + + + + + service.contacts.read(identifier,[fieldlist]) + + + + + service.contacts.save(fields) + + + + + service.contacts.delete(identifier) + + + + + + + Schedule: + + + + + service.schedule.read_list([search criteria]) + + + + + service.schedule.read(identifier,[fieldlist]) + + + + + service.schedule.save(fields) + + + + + service.schedule.delete(identifier) + + + + + + + Notes: + + + + + service.notes.read_list([search criteria]) + + + + + service.notes.read(identifier,[fieldlist]) + + + + + service.notes.save(fields) + + + + + service.notes.delete(identifier) + + + + + + + Todo: + + + + + service.todo.read_list(search criteria) + + + + + service.todo.read(identifer,[fieldlist]) + + + + + service.todo.save(fields) + + + + + service.todo.delete(identifier) + + + + + + + +
diff --git a/phpgwapi/doc/xmlrpc/gw_interface.txt b/phpgwapi/doc/xmlrpc/gw_interface.txt new file mode 100644 index 0000000000..a985826abe --- /dev/null +++ b/phpgwapi/doc/xmlrpc/gw_interface.txt @@ -0,0 +1,277 @@ + + +Common Groupware Interface Standard + +1 Scope + +As many different opensource and freesoftware groupware systems +are being developed, the full realization of the dream of +a connected world must be prefaced by an agreement to interoperate. +There are limited ways in which cooperation with commercial +groupware systems may be achecived, the majority if not +all of which were derived via the establishment of open +standards. These might include email (POP3/IMAP), contacts(LDAP,vcard), +or scheduling(ical/vcal). It is felt that while these have +proven themselves to be very useful, they are insufficient +to satisfy the real needs of a typical corporate environment. + +This document hopes to provide a reasonable recommendation +for a set of standardized methods to be used for groupware +services interaction. More specifically, it hopes to address +the need for such a standard as well as to spur discussion +about the common service names and methods themselves. + +Examples will be given for implementations in XML-RPC, since +this standard is relatively fixed and open. + +This document does not provide recommendations for the underlying +access control system which would allow or deny a particular +action. + +Also not discussed here is login and authorization to be +used for initial access to a service provider. + +2 The Services + +2.1 Overview + +There are a few common services types that will be needed +for minimum useability of a groupware server or application. +They are: + +* Contacts + +* Schedule + +* Notes + +* Todo + +These services are represented already in places such as +existing groupware client-server applications and also in +the PalmOS basic-4 buttons and applications. + +Within each of these services are some common methods that +would be called to store, retreive, or update data: + +* read_list + +* read + +* save + +* delete + +2.2 Detail + +2.2.1 Contacts + +The concept of contacts may encompass local addressbooks, +LDAP, and lists stored in other media. The purpose of the +contacts service is not to duplicate or attempt to replace +these. In some respects, it might do just that. But its +goal is more so to provide a common and shareable way for +the other core services to create, edit, and read a common +user and address list. All of the other services may use +the contact service to obtain record owner information to +be used in access control. They would also use them when +it is required to share this data, as with a meeting where +other local and non-local users will be invited to attend. + +Contacts may include the local installed user base, users +on other cooperative servers, or email addresses used for +limited cooperation with other groupware services that are +not compliant with this service scheme or implementations +thereof. It could also include individuals using web-based +or local ISP email services. The scope of this document, +however, is to define the service with regard to the common +methods to be used: + +* read_list + +This method is used to list contacts, with or without limits, +filters, or search criteria. In this way it can be used +for simple lists or to search for contact records and their +identifiers. The optional search criteria includes: + +1. start - Start at this identifier (integer: default 0) + +2. limit - Limit to this number of records returned(integer: + unlimited by default) + +3. fieldlist - limit to showing only these fields (array: + default to identifier, owner identifier, possibly firstname + and lastname) + +4. filter - Show records that are public or private only, + or other system-specific filters, e.g group or company(string: + default '') + +5. query - Search internal fieldlist for a value (string: + default '') + +The return for this method includes: + +1. count of number of records returned(integer) + +2. array consisting of: array: identifier => (array: fieldlist + key => value pairs) + +* read + +Once the identifier for a single contact record is known, +the contact may be read for more detail using this method. +This takes two parameters: + +1. identifier - (integer: no default) + +2. fieldlist - limit to showing only these fields (array: + default to identifier, owner identifier, possibly firstname + and lastname) + +And returns: + +1. array consisting of: array: identifier => (array: fieldlist + key => value pairs) + +* save + +This is a method used to save an existing record or create +a new one. If the identifier for an existing record is not +passed, a new entry will be created. + +* delete + +This will allow deletion of a record by passing its identifier. + +2.2.2 Schedule + +2.2.3 Notes + +2.2.4 Todo + +2.3 Examples in XML-RPC + +Query the contacts service for read_list, using only start +and limit to grab the first 5 records, starting with identifier +1. Additionally, return only the firstname and lastname +fields n_given and n_family (firstname and lastname in pseudo +vcard format): + + + +service.contacts.read_list + + + + + + + +start + +1 + + + +limit + +5 + + + +fields + + + +n_given + +n_given + + + +n_family + +n_family + + + + + + + +query + + + + + +filter + + + + + +sort + + + + + +order + + + + + + + + + + + + + +3 Conclusion + +This document outlined the following services and methods: + +3.1 Contacts: + +* service.contacts.read_list([search criteria]) + +* service.contacts.read(identifier,[fieldlist]) + +* service.contacts.save(fields) + +* service.contacts.delete(identifier) + +3.2 Schedule: + +* service.schedule.read_list([search criteria]) + +* service.schedule.read(identifier,[fieldlist]) + +* service.schedule.save(fields) + +* service.schedule.delete(identifier) + +3.3 Notes: + +* service.notes.read_list([search criteria]) + +* service.notes.read(identifier,[fieldlist]) + +* service.notes.save(fields) + +* service.notes.delete(identifier) + +3.4 Todo: + +* service.todo.read_list(search criteria) + +* service.todo.read(identifer,[fieldlist]) + +* service.todo.save(fields) + +* service.todo.delete(identifier)