$Id: README.txt,v 1.1.2.1 2009-07-06 09:26:12 alexk Exp $ 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