Интерфейс KittenDB FriendLists/Privacy Engine.
Папки друзей нумеруются от 1 до 30. Набор папок друзей представляется битовой маской - папке номер k соответствует 2k, затем все эти числа складываются. Кроме того, есть фиктивная папка друзей #0, в которой всегда находятся все друзья и у которой не может быть названия.
Например, если друг состоит в папках #1 и #3, то значение его маски папок друзей равно 23+21+20=13.
$MC_Friends = new Memcache (...);
Возвращает объект для доступа к друзьям пользователя $id, либо false, если такого объекта нет или соответствующий сервер сейчас недоступен.
Далее доступ к данным осуществляется по аналогии с memcached, с помощью функций вроде
$MC_Friends->get($key); $result = $MC_Friends->set($key,$value,0,600); $MC_Friends->delete($key); $MC_Friends->increment($key,$value);для специально построенных ключей $key и значений $value.
delete("user$id")
Удаляет информацию о пользователе $id, в частности, его список друзей, и все принадлежащие ему приватности. При этом у его друзей он автоматически не удаляется. После этого почти все операции с данным пользователем будут возвращать false; заново создать пользователя можно, добавив ему друга через set("friend{$id}_{$friend_id}", $mask).
get("friends$id")
get("friends{$id}_$mask")
get("friends$id#$mode")
get("friends{$id}_$mask#$mode")
Получает список друзей пользователя $id. Если указан параметр $mask, возвращаются только те друзья, которые содержатся в одной из папок, перечисленных в $mask (пример: $mask=8 -- только папка #3, $mask=10 -- папки 1 и 3). Параметр $mode равен 0 (значение по умолчанию), 1 (возвращать для каждого друга папки, в которые он входит) или 2 (возвращать для каждого друга набор папок и unixtime его добавления в друзья).
Результатом является строка, состоящая из чисел в десятичной системе, разделенных запятой. Первое значение - число N, количество друзей в ответе. Далее следует (mode+1)*N чисел, описывающих друзей в порядке возрастания id. Например, для $mode=2 каждый друг описывается тройкой ($friend_id,$cat_mask,$date).
Если сервер сейчас недоступен или запрос неправильно сформирован, возвращается false. Если список пуст, возвращается строка "0".
get("friendcnt{$id}")
get("friendcnt{$id}_{$mask}")
Возвращает количество друзей пользователя id, всех или принадлежащих одной из папок, заданных маской mask.
get("recent_friends$id#$num")
Возвращает $num последних добавленных друзей пользователя $id в антихронологическом порядке.
Каждый друг представлен тройкой чисел ($friend_id,$cat,$date).
set("friends{$id}_{$cat}", implode(",", $friend_id_list))
Устанавливает список друзей пользователя $id, которые должны быть в категории (т.е. папке) $cat, где 1 <= $cat <= 30. Если какого-то пользователя, перечисленного в $friend_id_list, нет в друзьях, он игнорируется (в друзья не добавляется).
get("friend{$id}_{$friend_id}")
Возвращает маску папок, ассоциированную с пользователем $friend_id в списке друзей пользователя $id, либо ничего (false), если этого пользователя нет в списке друзей. Следует отметить, что если пользователь есть в списке друзей, значение будет положительным целым числом.
set("friend{$id}_{$friend_id}", $mask)
replace("friend{$id}_{$friend_id}", $mask)
delete("friend{$id}_{$friend_id}")
Эти операции соответственно добавляют, редактируют и удаляют пользователя $friend_id внутри списка друзей пользователя $id. Первые две из них устанавливают новую маску папок для этого друга; при этом операция set добавляет пользователя в друзья, если его там еще нет, и даже создает пользователя $id, если до этого о нем не было никакой информации, а replace только редактирует существующего друга. Если не выбрано ни одной папки друзей, следует использовать $mask=1.
increment("friend{$id}_{$friend_id}", $mask)
decrement("friend{$id}_{$friend_id}", $mask)
Здесь mask - это маска, задающая набор папок, в которые надо добавить друга или из которых надо его убрать. Следует отметить, что эти операции реализованы с помощью логических OR и AND, а не с помощью сложения и вычитания, т.е. добавление друга в папку, в которой он уже есть, ни на что не повлияет и ничего не испортит. Возвращаемое значение - новая маска папок для данного друга.
delete("friend_cat{$user_id}_{$cat}")
Удаляет папку друзей и все ссылки на нее в списках приватности.
get("friendreq{$id}_{$friend_id}")
add("friendreq{$id}_{$friend_id}", $mask)
set("friendreq{$id}_{$friend_id}", $mask)
replace("friendreq{$id}_{$friend_id}", $mask)
delete("friendreq{$id}_{$friend_id}")
Эти функции получают, добавляют, редактируют и удаляют заявку в друзья, поданную пользователем $friend_id на добавление в друзья пользователя $id. Передаваемая маска - это папки друзей, в которые $friend_id хотел бы занести $id в своем списке друзей (а не наоборот). Метод add не редактирует уже существующую заявку, а только добавляет новую, а replace - наоборот.
delete("requests{$id}")
Удаляет все заявки в друзья.
get("requests{$id}")
get("requests{$id}#{$num}")
Возвращает заявки в друзья, направленные для одобрения пользователю $id. В первом случае заявки возвращаются все заявки в порядке возрастания friend_id (id заявителя), во втором - последние num штук в антихронологическом порядке. Результат - строка, состоящая из 3N+1 числа: первое число - общее количество заявок, следующие N троек описывают заявки в формате ($id,$mask,$date).
Приватность -- это некоторый набор правил, определяющих множество пользователей, которым разрешен доступ к тому или иному объекту. В рамках описываемой системы для обращения к приватности надо знать id ее владельца (пользователя, которому принадлежит нужный объект) и некоторый уникальный ключ приватности. Значение приватности есть набор правил, включающий или исключающих из рассмотрения некоторые папки друзей владельца приватности либо отдельных пользователей. Такой набор правил обычно передается в виде строки специального вида.
set("privacy{$id}_{$priv_key}", $priv_text);
replace("privacy{$id}_{$priv_key}", $priv_text);
Здесь id - это id владельца приватности, $priv_key - ключ приватности, $priv_text - описание приватности. Первая из этих функций при необходимости создает несуществующего пользователя и приватность, а вторая только редактирует существующую.
$priv_text = get("privacy{$id}_{$priv_key}")
Возвращает значение приватности в виде строки, не обязательно той же самой, что была использована при создании или редактировании приватности, но эквивалентной ей. Если указанный пользователь или приватность не определены, возвращает false.
=== Проверка приватности ===
<code>get("{$user_id}~{$owner_id}:{$privacy_key}")
Здесь $user_id - пользователь, запросивший проверку, $owner_id - владелец приватности, $privacy_key - ключ нужной приватности. Результат:
| Результат | Смысл |
|---|---|
| false | Приватность не существует |
| ? | Приватность не существует |
| 0 | Запрещено |
| 1 | Запрещено, если только пользователь не является другом друга |
| 2 | Разрешено, если только пользователь не является другом друга |
| 3 | Разрешено |
Для проверки результата можно пользоваться условием
... if ($result >= 2) { ... }.
Можно запросить проверку сразу нескольких приватностей:
$res_array = $MC_Friends->get(array($key1, $key2, $key3, ...)); $res1 = $res_array[$key1]; ...В этом случае запрашиваемые приватности должны иметь общего владельца, либо запрос следует направлять распределяющему серверу, полученному по
$inc->chooseFriendsPrivacyServer(0).
get("{$user_id}~{$owner_id}:{$privacy_key1},{$privacy_key2},...,{$privacy_keyN}")
В случае успешной проверки результат - строка ровно из N символов, представляющих собой результат проверки перечисленных приватностей; если какой-то приватности не существует, символ результата будет '?'.
Альтернативный режим нужен для быстрого вычисления количества общих друзей с теми или иными пользователями.
См. Общие друзья через friends-engine.