README.txt in User Relationships 5.2

Author scottgifford http://drupal.org/user/245699

= RPC calls for relationship management =

This module allows relationships to be requested, approved, deleted,
and listed via Drupal RPC calls.

Errors will be returned via the RPC handler's standard error reporting
mechanism. In the case of XML-RPC, they will be returned as XML-RPC faults
with an error number as described below; for JSON the error number will
be the first number preceded by a pound sign.  The errors also include
an error string describing the error in a human-readable way.

== user_relationships.types ==

The "user_relationships.types" call gets a list of all relationship types
currently recognized by the system.  It takes the following arguments:

  1. version: API version in use, currently always 1

On success, it will return an array of structures containing these fields:

  * rtid: The ID of theis relationship types.
  * name: Name of relationship type.
  * plural_name: Properly pluralized name of relationship type, for user display

The structures may also contain other fields, which are subject to change
and should not be relied on.

On failure, it may return one of these errors:
  * A general error, containing a human-readable message

== user_relationships.search ==

The "user_relationships.mine" call gets a list of all the currently
logged in user's relationships, both active and pending.

It takes the following arguments:

  1. version: API version in use, currently always 1
  2. query: Query, as described below.

On success, it will return an array of structures containing these fields:

  * rid: ID of this particular relationship
  * initiator: Who initiated this request, always either "me" or "otherguy".  For approved relationships, it will always be "me".
  * otherguy: ID of the other user in this relationship, regardless of whether they were requester or requestee.
  * requester_id: ID of the user that requested this relationship
  * requestee_id: ID of the user this relationship was requested of
  * rtid: Relationship Type ID; see user_relationships.types
  * approved: Approved flag.  If this is "1", both users have approved this relationship.  If it is 0, the relationship has not been approved; if the "requester_id" is the same as the current UID, it is awaiting approval from the other party, while if the "requestee_id" is the same as the current UID it is awaiting approval from this user.
  * created_at: Unix timestamp of time when relationship was first requested
  * updated_at: Unix timestamp of time when relationship was last modified
  * name: Name of this relationship type
  * plural_name: Properly pluralized name of this relationship type

The structures may also contain other fields, which are subject to change
and should not be relied on.

If there are no results, an empty array will be returned, not an error.

On failure, it may return one of these errors:

  * A general error, containing a human-readable message


== user_relationships.mine ==

The "user_relationships.mine" call gets a list of all the currently
logged in user's relationships, both active and pending.

It takes the following arguments:

  1. version: API version in use, currently always 1

On success, it will return an array of structures like those in
user_relationships.search.

On failure, it may return one of these errors:

  * A general error, containing a human-readable message

== user_relationships.delete ==

The "user_relationships.delete" call deletes an existing or pending
relationship.  It should be used to remove existing relationships with
users, cancel an outstanding relationship requests from the current user,
or decline another user's relationship request.

It takes the following arguments:

  1. version: API version in use, currently always 1
  2. rid: Relationship ID, as returned by user_relationships.mine
  3. reason: Reason for deleting the relationship ("cancel", "disapprove", or "remove")

On success, it will return a structure with a bunch of random stuff in it.

On failure, it may return one of these errors:

  * A general error, containing a human-readable message

== user_relationships.delete.matching ==

The "user_relationships.delete.matching" call deletes existing or pending
relationship according to the given query.  It can be used to remove
existing relationships with users, cancel an outstanding relationship
requests from the current user, or decline another user's relationship
request.

It takes the following arguments:
  1. version: API version in use, currently always 1
  2. query: Query, as described below.
  3. reason: Reason for deleting the relationship ("cancel", "disapprove", or "remove")

On success, it will return the deleted relationships, in the same
format as for user_relationships.search.  If there were no matching
relationships, an empty array will be returned, not an error.

On failure, it may return one of these errors:

  * A general error, containing a human-readable message

== user_relationships.approve ==

The "user_relationships.approve" call approves a pending relationship
request from another user.

It takes the following arguments:
  1. version: API version in use, currently always 1
  2. rid: Relationship ID, as returned by user_relationships.mine

On success, it will return a structure with a bunch of random stuff in it.

On failure, it may return one of these errors:
  * A general error, containing a human-readable message

== user_relationships.request ==

The "user_relationships.request" call requests a new relationship with
another user.  Drupal will automatically send an email to that user
notifying them of the request.

It takes the following arguments:
  1. version: API version in use, currently always 1
  2. uid: UID of the other user
  3. type: Relationship type name; see user_relationships.types

On success, it will return a structure with a bunch of random stuff in it.

On failure, it may return one of these errors:

  * A general error, containing a human-readable message

= Queries =

The query for a relationship search is an array of structures. Each
structure has two fields.  "search" contains the field that's being
searched, and "value" contains something to search for.

For searching fields, you can simply use the field name for search,
and an exact value for the value.  Only exact matches are supported,
and the query will always have an implicit clause limiting results to
your own relationships.

All parts of the query must be true for a result to match.  Pattern
matching and subqueries are not supported.

Currently, all fields are searchable except "created_at" and "updated_at".

= Examples =

To search for any pending relationship requests initiated by others, search for:

    approved=0
    initaitor=otherguy

To remove all relationships with the user with UID 1, delete with the query:

    otherguy=1

To delete only the friend relationship, instead use:

    otherguy=1
    name=friend