From fba8c776e16d87e3e5b944cd156ec94e3c1aff6a Mon Sep 17 00:00:00 2001 From: Thomas Mueller Date: Fri, 23 Nov 2012 00:30:11 +0100 Subject: [PATCH 1/7] plugin mechanism implemented --- lib/public/contacts.php | 227 ++++++++++++++++++++++++++++------------ 1 file changed, 161 insertions(+), 66 deletions(-) diff --git a/lib/public/contacts.php b/lib/public/contacts.php index 5762fd28e0..51d4e03f00 100644 --- a/lib/public/contacts.php +++ b/lib/public/contacts.php @@ -26,78 +26,173 @@ * */ +namespace OC { + interface AddressBook { + + /** + * @return string defining the technical unique key + */ + public function getKey(); + + /** + * In comparison to getKey() this function returns a human readable (maybe translated) name + * @return mixed + */ + public function getDisplayName(); + + /** + * @param $pattern + * @param $searchProperties + * @param $options + * @return mixed + */ + public function search($pattern, $searchProperties, $options); +// // dummy results +// return array( +// array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c', 'GEO' => '37.386013;-122.082932'), +// array('id' => 5, 'FN' => 'Thomas Tanghus', 'EMAIL' => array('d@e.f', 'g@h.i')), +// ); + + /** + * @param $properties + * @return mixed + */ + public function createOrUpdate($properties); +// // dummy +// return array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c', +// 'PHOTO' => 'VALUE=uri:http://www.abc.com/pub/photos/jqpublic.gif', +// 'ADR' => ';;123 Main Street;Any Town;CA;91921-1234' +// ); + + /** + * @return mixed + */ + public function isReadOnly(); + + /** + * @param $id + * @return mixed + */ + public function delete($id); + } +} + // use OCP namespace for all classes that are considered public. // This means that they should be used by apps instead of the internal ownCloud classes -namespace OCP; - -/** - * This class provides access to the contacts app. Use this class exclusively if you want to access contacts. - * - * Contacts in general will be expressed as an array of key-value-pairs. - * The keys will match the property names defined in https://tools.ietf.org/html/rfc2426#section-1 - * - * Proposed workflow for working with contacts: - * - search for the contacts - * - manipulate the results array - * - createOrUpdate will save the given contacts overwriting the existing data - * - * For updating it is mandatory to keep the id. - * Without an id a new contact will be created. - * - */ -class Contacts -{ - /** - * This function is used to search and find contacts within the users address books. - * In case $pattern is empty all contacts will be returned. - * - * @param string $pattern which should match within the $searchProperties - * @param array $searchProperties defines the properties within the query pattern should match - * @param array $options - for future use. One should always have options! - * @return array of contacts which are arrays of key-value-pairs - */ - public static function search($pattern, $searchProperties = array(), $options = array()) { - - // dummy results - return array( - array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c', 'GEO' => '37.386013;-122.082932'), - array('id' => 5, 'FN' => 'Thomas Tanghus', 'EMAIL' => array('d@e.f', 'g@h.i')), - ); - } +namespace OCP { /** - * This function can be used to delete the contact identified by the given id + * This class provides access to the contacts app. Use this class exclusively if you want to access contacts. * - * @param object $id the unique identifier to a contact - * @return bool successful or not - */ - public static function delete($id) { - return false; - } - - /** - * This function is used to create a new contact if 'id' is not given or not present. - * Otherwise the contact will be updated by replacing the entire data set. + * Contacts in general will be expressed as an array of key-value-pairs. + * The keys will match the property names defined in https://tools.ietf.org/html/rfc2426#section-1 * - * @param array $properties this array if key-value-pairs defines a contact - * @return array representing the contact just created or updated - */ - public static function createOrUpdate($properties) { - - // dummy - return array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c', - 'PHOTO' => 'VALUE=uri:http://www.abc.com/pub/photos/jqpublic.gif', - 'ADR' => ';;123 Main Street;Any Town;CA;91921-1234' - ); - } - - /** - * Check if contacts are available (e.g. contacts app enabled) + * Proposed workflow for working with contacts: + * - search for the contacts + * - manipulate the results array + * - createOrUpdate will save the given contacts overwriting the existing data + * + * For updating it is mandatory to keep the id. + * Without an id a new contact will be created. * - * @return bool true if enabled, false if not */ - public static function isEnabled() { - return false; - } + class Contacts { -} + /** + * This function is used to search and find contacts within the users address books. + * In case $pattern is empty all contacts will be returned. + * + * @param string $pattern which should match within the $searchProperties + * @param array $searchProperties defines the properties within the query pattern should match + * @param array $options - for future use. One should always have options! + * @return array of contacts which are arrays of key-value-pairs + */ + public static function search($pattern, $searchProperties = array(), $options = array()) { + + $result = array(); + foreach(self::$address_books as $address_book) { + $result = $result + $address_book->search($pattern, $searchProperties, $options); + } + + return $result; + } + + /** + * This function can be used to delete the contact identified by the given id + * + * @param object $id the unique identifier to a contact + * @param $address_book_key + * @return bool successful or not + */ + public static function delete($id, $address_book_key) { + if (!array_key_exists($address_book_key, self::$address_books)) + return null; + + $address_book = self::$address_books[$address_book_key]; + if ($address_book->isReadOnly()) + return null; + + return $address_book->delete($id); + } + + /** + * This function is used to create a new contact if 'id' is not given or not present. + * Otherwise the contact will be updated by replacing the entire data set. + * + * @param array $properties this array if key-value-pairs defines a contact + * @param $address_book_key string to identify the address book in which the contact shall be created or updated + * @return array representing the contact just created or updated + */ + public static function createOrUpdate($properties, $address_book_key) { + + if (!array_key_exists($address_book_key, self::$address_books)) + return null; + + $address_book = self::$address_books[$address_book_key]; + if ($address_book->isReadOnly()) + return null; + + return $address_book->createOrUpdate($properties); + } + + /** + * Check if contacts are available (e.g. contacts app enabled) + * + * @return bool true if enabled, false if not + */ + public static function isEnabled() { + return !empty(self::$address_books); + } + + /** + * @param \OC\AddressBook $address_book + */ + public static function registerAddressBook(\OC\AddressBook $address_book) { + self::$address_books[$address_book->getKey()] = $address_book; + } + + /** + * @param \OC\AddressBook $address_book + */ + public static function unregisterAddressBook(\OC\AddressBook $address_book) { + unset(self::$address_books[$address_book->getKey()]); + } + + /** + * @return array + */ + public static function getAddressBooks() { + $result = array(); + foreach(self::$address_books as $address_book) { + $result[$address_book->getKey()] = $address_book->getDisplayName(); + } + + return $result; + } + + /** + * @var \OC\AddressBook[] which holds all registered address books + */ + private static $address_books = array(); + } +} \ No newline at end of file From 5b1dea56e551df1306bd2046c3d06f1e589b4c03 Mon Sep 17 00:00:00 2001 From: Thomas Mueller Date: Fri, 23 Nov 2012 21:48:39 +0100 Subject: [PATCH 2/7] change name to IAddressBook --- lib/public/contacts.php | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/lib/public/contacts.php b/lib/public/contacts.php index 51d4e03f00..36195ef9c2 100644 --- a/lib/public/contacts.php +++ b/lib/public/contacts.php @@ -27,7 +27,7 @@ */ namespace OC { - interface AddressBook { + interface IAddressBook { /** * @return string defining the technical unique key @@ -165,16 +165,16 @@ namespace OCP { } /** - * @param \OC\AddressBook $address_book + * @param \OC\IAddressBook $address_book */ - public static function registerAddressBook(\OC\AddressBook $address_book) { + public static function registerAddressBook(\OC\IAddressBook $address_book) { self::$address_books[$address_book->getKey()] = $address_book; } /** - * @param \OC\AddressBook $address_book + * @param \OC\IAddressBook $address_book */ - public static function unregisterAddressBook(\OC\AddressBook $address_book) { + public static function unregisterAddressBook(\OC\IAddressBook $address_book) { unset(self::$address_books[$address_book->getKey()]); } @@ -191,7 +191,7 @@ namespace OCP { } /** - * @var \OC\AddressBook[] which holds all registered address books + * @var \OC\IAddressBook[] which holds all registered address books */ private static $address_books = array(); } From 2d597c2238c40ff0291fc80a4807aee6fc7bc4fc Mon Sep 17 00:00:00 2001 From: Thomas Mueller Date: Sat, 24 Nov 2012 00:01:58 +0100 Subject: [PATCH 3/7] first unit tests implemented --- lib/public/contacts.php | 15 +++++-- tests/lib/public/contacts.php | 80 +++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+), 4 deletions(-) create mode 100644 tests/lib/public/contacts.php diff --git a/lib/public/contacts.php b/lib/public/contacts.php index 36195ef9c2..d14806bd0c 100644 --- a/lib/public/contacts.php +++ b/lib/public/contacts.php @@ -67,7 +67,7 @@ namespace OC { /** * @return mixed */ - public function isReadOnly(); + public function getPermissions(); /** * @param $id @@ -129,7 +129,7 @@ namespace OCP { return null; $address_book = self::$address_books[$address_book_key]; - if ($address_book->isReadOnly()) + if ($address_book->getPermissions() & \OCP\PERMISSION_DELETE) return null; return $address_book->delete($id); @@ -149,7 +149,7 @@ namespace OCP { return null; $address_book = self::$address_books[$address_book_key]; - if ($address_book->isReadOnly()) + if ($address_book->getPermissions() & \OCP\PERMISSION_CREATE) return null; return $address_book->createOrUpdate($properties); @@ -190,9 +190,16 @@ namespace OCP { return $result; } + /** + * removes all registered address book instances + */ + public static function clear() { + self::$address_books = array(); + } + /** * @var \OC\IAddressBook[] which holds all registered address books */ private static $address_books = array(); } -} \ No newline at end of file +} diff --git a/tests/lib/public/contacts.php b/tests/lib/public/contacts.php new file mode 100644 index 0000000000..abe0e1f625 --- /dev/null +++ b/tests/lib/public/contacts.php @@ -0,0 +1,80 @@ +. + */ + +OC::autoload('OCP\Contacts'); + +class Test_Contacts extends PHPUnit_Framework_TestCase +{ + + public function setUp() { + + OCP\Contacts::clear(); + } + + public function tearDown() { + } + + public function testDisabledIfEmpty() { + // pretty simple + $this->assertFalse(OCP\Contacts::isEnabled()); + } + + public function testEnabledAfterRegister() { + // create mock for the addressbook + $stub = $this->getMock("SimpleAddressBook", array('getKey')); + + // we expect getKey to be called once + $stub->expects($this->once()) + ->method('getKey'); + + // not enabled before register + $this->assertFalse(OCP\Contacts::isEnabled()); + + // register the address book + OCP\Contacts::registerAddressBook($stub); + + // contacts api shall be enabled + $this->assertTrue(OCP\Contacts::isEnabled()); + } + + // + // TODO: test unregister + // + + public function testAddressBookEnumeration() { + // create mock for the addressbook + $stub = $this->getMock("SimpleAddressBook", array('getKey', 'getDisplayName')); + + // setup return for method calls + $stub->expects($this->any()) + ->method('getKey') + ->will($this->returnValue('SIMPLE_ADDRESS_BOOK')); + $stub->expects($this->any()) + ->method('getDisplayName') + ->will($this->returnValue('A very simple Addressbook')); + + // register the address book + OCP\Contacts::registerAddressBook($stub); + $all_books = OCP\Contacts::getAddressBooks(); + + $this->assertEquals(1, count($all_books)); + } +} From f99497a05a14ccf3c96ece71ae963a2eb482f4b6 Mon Sep 17 00:00:00 2001 From: Thomas Mueller Date: Sun, 25 Nov 2012 13:29:58 +0100 Subject: [PATCH 4/7] test for search and unregister added --- lib/public/contacts.php | 4 +-- tests/lib/public/contacts.php | 57 +++++++++++++++++++++++++++++++---- 2 files changed, 53 insertions(+), 8 deletions(-) diff --git a/lib/public/contacts.php b/lib/public/contacts.php index d14806bd0c..412600dd7f 100644 --- a/lib/public/contacts.php +++ b/lib/public/contacts.php @@ -108,10 +108,10 @@ namespace OCP { * @return array of contacts which are arrays of key-value-pairs */ public static function search($pattern, $searchProperties = array(), $options = array()) { - $result = array(); foreach(self::$address_books as $address_book) { - $result = $result + $address_book->search($pattern, $searchProperties, $options); + $r = $address_book->search($pattern, $searchProperties, $options); + $result = array_merge($result, $r); } return $result; diff --git a/tests/lib/public/contacts.php b/tests/lib/public/contacts.php index abe0e1f625..23994667a2 100644 --- a/tests/lib/public/contacts.php +++ b/tests/lib/public/contacts.php @@ -41,8 +41,10 @@ class Test_Contacts extends PHPUnit_Framework_TestCase // create mock for the addressbook $stub = $this->getMock("SimpleAddressBook", array('getKey')); - // we expect getKey to be called once - $stub->expects($this->once()) + // we expect getKey to be called twice: + // first time on register + // second time on un-register + $stub->expects($this->exactly(2)) ->method('getKey'); // not enabled before register @@ -53,11 +55,13 @@ class Test_Contacts extends PHPUnit_Framework_TestCase // contacts api shall be enabled $this->assertTrue(OCP\Contacts::isEnabled()); - } - // - // TODO: test unregister - // + // unregister the address book + OCP\Contacts::unregisterAddressBook($stub); + + // not enabled after register + $this->assertFalse(OCP\Contacts::isEnabled()); + } public function testAddressBookEnumeration() { // create mock for the addressbook @@ -76,5 +80,46 @@ class Test_Contacts extends PHPUnit_Framework_TestCase $all_books = OCP\Contacts::getAddressBooks(); $this->assertEquals(1, count($all_books)); + $this->assertEquals('A very simple Addressbook', $all_books['SIMPLE_ADDRESS_BOOK']); + } + + public function testSearchInAddressBook() { + // create mock for the addressbook + $stub1 = $this->getMock("SimpleAddressBook1", array('getKey', 'getDisplayName', 'search')); + $stub2 = $this->getMock("SimpleAddressBook2", array('getKey', 'getDisplayName', 'search')); + + $searchResult1 = array( + array('id' => 0, 'FN' => 'Frank Karlitschek', 'EMAIL' => 'a@b.c', 'GEO' => '37.386013;-122.082932'), + array('id' => 5, 'FN' => 'Klaas Freitag', 'EMAIL' => array('d@e.f', 'g@h.i')), + ); + $searchResult2 = array( + array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c'), + array('id' => 5, 'FN' => 'Thomas Tanghus', 'EMAIL' => array('d@e.f', 'g@h.i')), + ); + + // setup return for method calls for $stub1 + $stub1->expects($this->any())->method('getKey')->will($this->returnValue('SIMPLE_ADDRESS_BOOK1')); + $stub1->expects($this->any())->method('getDisplayName')->will($this->returnValue('Address book ownCloud Inc')); + $stub1->expects($this->any())->method('search')->will($this->returnValue($searchResult1)); + + // setup return for method calls for $stub2 + $stub2->expects($this->any())->method('getKey')->will($this->returnValue('SIMPLE_ADDRESS_BOOK2')); + $stub2->expects($this->any())->method('getDisplayName')->will($this->returnValue('Address book ownCloud Community')); + $stub2->expects($this->any())->method('search')->will($this->returnValue($searchResult2)); + + // register the address books + OCP\Contacts::registerAddressBook($stub1); + OCP\Contacts::registerAddressBook($stub2); + $all_books = OCP\Contacts::getAddressBooks(); + + // assert the count - doesn't hurt + $this->assertEquals(2, count($all_books)); + + // perform the search + $result = OCP\Contacts::search('x', array()); + + // we expect 4 hits + $this->assertEquals(4, count($result)); + } } From 35e55214e24116a4501260ff4ce94c171404737b Mon Sep 17 00:00:00 2001 From: Thomas Mueller Date: Sun, 2 Dec 2012 11:54:30 +0100 Subject: [PATCH 5/7] [Contacts API] example for searching added --- lib/public/contacts.php | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/lib/public/contacts.php b/lib/public/contacts.php index 412600dd7f..6842f40f1b 100644 --- a/lib/public/contacts.php +++ b/lib/public/contacts.php @@ -102,6 +102,38 @@ namespace OCP { * This function is used to search and find contacts within the users address books. * In case $pattern is empty all contacts will be returned. * + * Example: + * Following function shows how to search for contacts for the name and the email address. + * + * public static function getMatchingRecipient($term) { + * // The API is not active -> nothing to do + * if (!\OCP\Contacts::isEnabled()) { + * return array(); + * } + * + * $result = \OCP\Contacts::search($term, array('FN', 'EMAIL')); + * $receivers = array(); + * foreach ($result as $r) { + * $id = $r['id']; + * $fn = $r['FN']; + * $email = $r['EMAIL']; + * if (!is_array($email)) { + * $email = array($email); + * } + * + * // loop through all email addresses of this contact + * foreach ($email as $e) { + * $displayName = $fn . " <$e>"; + * $receivers[] = array('id' => $id, + * 'label' => $displayName, + * 'value' => $displayName); + * } + * } + * + * return $receivers; + * } + * + * * @param string $pattern which should match within the $searchProperties * @param array $searchProperties defines the properties within the query pattern should match * @param array $options - for future use. One should always have options! From 889e55fdac56ab3eecd6ce65db19e3dfeeff44ea Mon Sep 17 00:00:00 2001 From: Thomas Mueller Date: Thu, 6 Dec 2012 23:51:35 +0100 Subject: [PATCH 6/7] [contacts_api] update documentation --- lib/public/contacts.php | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/lib/public/contacts.php b/lib/public/contacts.php index 6842f40f1b..ca0b15b2c7 100644 --- a/lib/public/contacts.php +++ b/lib/public/contacts.php @@ -41,10 +41,10 @@ namespace OC { public function getDisplayName(); /** - * @param $pattern - * @param $searchProperties - * @param $options - * @return mixed + * @param string $pattern which should match within the $searchProperties + * @param array $searchProperties defines the properties within the query pattern should match + * @param array $options - for future use. One should always have options! + * @return array of contacts which are arrays of key-value-pairs */ public function search($pattern, $searchProperties, $options); // // dummy results @@ -54,8 +54,8 @@ namespace OC { // ); /** - * @param $properties - * @return mixed + * @param array $properties this array if key-value-pairs defines a contact + * @return array representing the contact just created or updated */ public function createOrUpdate($properties); // // dummy @@ -70,8 +70,8 @@ namespace OC { public function getPermissions(); /** - * @param $id - * @return mixed + * @param object $id the unique identifier to a contact + * @return bool successful or not */ public function delete($id); } From 4cc895aa0a7d73e6817bfcc9f1fc4d76740b0513 Mon Sep 17 00:00:00 2001 From: Thomas Mueller Date: Sat, 8 Dec 2012 16:42:54 +0100 Subject: [PATCH 7/7] [contacts_api] move addressbook to it's own file --- lib/iaddressbook.php | 72 +++++++++++++++++++++++++++++++++++++++++ lib/public/contacts.php | 51 ----------------------------- 2 files changed, 72 insertions(+), 51 deletions(-) create mode 100644 lib/iaddressbook.php diff --git a/lib/iaddressbook.php b/lib/iaddressbook.php new file mode 100644 index 0000000000..3920514036 --- /dev/null +++ b/lib/iaddressbook.php @@ -0,0 +1,72 @@ +. + * + */ + +namespace OC { + interface IAddressBook { + + /** + * @return string defining the technical unique key + */ + public function getKey(); + + /** + * In comparison to getKey() this function returns a human readable (maybe translated) name + * @return mixed + */ + public function getDisplayName(); + + /** + * @param string $pattern which should match within the $searchProperties + * @param array $searchProperties defines the properties within the query pattern should match + * @param array $options - for future use. One should always have options! + * @return array of contacts which are arrays of key-value-pairs + */ + public function search($pattern, $searchProperties, $options); +// // dummy results +// return array( +// array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c', 'GEO' => '37.386013;-122.082932'), +// array('id' => 5, 'FN' => 'Thomas Tanghus', 'EMAIL' => array('d@e.f', 'g@h.i')), +// ); + + /** + * @param array $properties this array if key-value-pairs defines a contact + * @return array representing the contact just created or updated + */ + public function createOrUpdate($properties); +// // dummy +// return array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c', +// 'PHOTO' => 'VALUE=uri:http://www.abc.com/pub/photos/jqpublic.gif', +// 'ADR' => ';;123 Main Street;Any Town;CA;91921-1234' +// ); + + /** + * @return mixed + */ + public function getPermissions(); + + /** + * @param object $id the unique identifier to a contact + * @return bool successful or not + */ + public function delete($id); + } +} diff --git a/lib/public/contacts.php b/lib/public/contacts.php index ca0b15b2c7..ab46614c8f 100644 --- a/lib/public/contacts.php +++ b/lib/public/contacts.php @@ -26,57 +26,6 @@ * */ -namespace OC { - interface IAddressBook { - - /** - * @return string defining the technical unique key - */ - public function getKey(); - - /** - * In comparison to getKey() this function returns a human readable (maybe translated) name - * @return mixed - */ - public function getDisplayName(); - - /** - * @param string $pattern which should match within the $searchProperties - * @param array $searchProperties defines the properties within the query pattern should match - * @param array $options - for future use. One should always have options! - * @return array of contacts which are arrays of key-value-pairs - */ - public function search($pattern, $searchProperties, $options); -// // dummy results -// return array( -// array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c', 'GEO' => '37.386013;-122.082932'), -// array('id' => 5, 'FN' => 'Thomas Tanghus', 'EMAIL' => array('d@e.f', 'g@h.i')), -// ); - - /** - * @param array $properties this array if key-value-pairs defines a contact - * @return array representing the contact just created or updated - */ - public function createOrUpdate($properties); -// // dummy -// return array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c', -// 'PHOTO' => 'VALUE=uri:http://www.abc.com/pub/photos/jqpublic.gif', -// 'ADR' => ';;123 Main Street;Any Town;CA;91921-1234' -// ); - - /** - * @return mixed - */ - public function getPermissions(); - - /** - * @param object $id the unique identifier to a contact - * @return bool successful or not - */ - public function delete($id); - } -} - // use OCP namespace for all classes that are considered public. // This means that they should be used by apps instead of the internal ownCloud classes namespace OCP {