1
0

IAddressBook.php 3.2 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697
  1. <?php
  2. /**
  3. * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
  4. * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
  5. * SPDX-License-Identifier: AGPL-3.0-only
  6. */
  7. // use OCP namespace for all classes that are considered public.
  8. // This means that they should be used by apps instead of the internal Nextcloud classes
  9. namespace OCP {
  10. /**
  11. * Interface IAddressBook
  12. *
  13. * @since 5.0.0
  14. */
  15. interface IAddressBook {
  16. /**
  17. * @return string defining the technical unique key
  18. * @since 5.0.0
  19. */
  20. public function getKey();
  21. /**
  22. * @return string defining the unique uri
  23. * @since 16.0.0
  24. */
  25. public function getUri(): string;
  26. /**
  27. * In comparison to getKey() this function returns a human readable (maybe translated) name
  28. * @return mixed
  29. * @since 5.0.0
  30. */
  31. public function getDisplayName();
  32. /**
  33. * @param string $pattern which should match within the $searchProperties
  34. * @param array $searchProperties defines the properties within the query pattern should match
  35. * @param array $options Options to define the output format and search behavior
  36. * - 'types' boolean (since 15.0.0) If set to true, fields that come with a TYPE property will be an array
  37. * example: ['id' => 5, 'FN' => 'Thomas Tanghus', 'EMAIL' => ['type => 'HOME', 'value' => 'g@h.i']]
  38. * - 'escape_like_param' - If set to false wildcards _ and % are not escaped
  39. * - 'limit' - Set a numeric limit for the search results
  40. * - 'offset' - Set the offset for the limited search results
  41. * - 'wildcard' - (since 23.0.0) Whether the search should use wildcards
  42. * @psalm-param array{types?: bool, escape_like_param?: bool, limit?: int, offset?: int, wildcard?: bool} $options
  43. * @return array an array of contacts which are arrays of key-value-pairs
  44. * example result:
  45. * [
  46. * ['id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c', 'GEO' => '37.386013;-122.082932'],
  47. * ['id' => 5, 'FN' => 'Thomas Tanghus', 'EMAIL' => ['d@e.f', 'g@h.i']]
  48. * ]
  49. * @since 5.0.0
  50. */
  51. public function search($pattern, $searchProperties, $options);
  52. /**
  53. * @param array $properties this array if key-value-pairs defines a contact
  54. * @return array an array representing the contact just created or updated
  55. * @since 5.0.0
  56. */
  57. public function createOrUpdate($properties);
  58. // // dummy
  59. // return array('id' => 0, 'FN' => 'Thomas Müller', 'EMAIL' => 'a@b.c',
  60. // 'PHOTO' => 'VALUE=uri:http://www.abc.com/pub/photos/jqpublic.gif',
  61. // 'ADR' => ';;123 Main Street;Any Town;CA;91921-1234'
  62. // );
  63. /**
  64. * @return mixed
  65. * @since 5.0.0
  66. */
  67. public function getPermissions();
  68. /**
  69. * @param int $id the unique identifier to a contact
  70. * @return bool successful or not
  71. * @since 5.0.0
  72. */
  73. public function delete($id);
  74. /**
  75. * Returns true if this address-book is not owned by the current user,
  76. * but shared with them.
  77. *
  78. * @return bool
  79. * @since 20.0.0
  80. */
  81. public function isShared(): bool;
  82. /**
  83. * @return bool
  84. * @since 20.0.0
  85. */
  86. public function isSystemAddressBook(): bool;
  87. }
  88. }