From 35e55214e24116a4501260ff4ce94c171404737b Mon Sep 17 00:00:00 2001
From: Thomas Mueller <thomas.mueller@tmit.eu>
Date: Sun, 2 Dec 2012 11:54:30 +0100
Subject: [PATCH] [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!