Difference between revisions of "XML-RPC Protocol Method: getcircle"

Latest revision as of 00:06, 21 September 2010

Returns a verbose list of information about a user's watch list (those that the user has subscribed to) and/or the user's trust list (those that the user has granted access to). Also can get the user's watched-by list, trusted-by list, content filters and trust groups.

Inputs

username Scalar. Required. Username of user logging in.

auth_method Scalar. Optional. Authentication method used for this request. The default value is "clear", for plain-text authentication. "cookie" and any of the challenge-response methods are also acceptable.

password Deprecated. Scalar. Optional. Password of user logging in in plaintext. If using the "clear" authentication method, either this or "hpassword" must be present.

hpassword Deprecated. Scalar. Optional. MD5 digest of user's password. Not much more secure than password, but at least it's not in plain text.

auth_challenge Scalar. Optional. If using challenge-response authentication, this should be the challenge that was issued to you by the server.

auth_response Scalar. Optional. If using challenge-response authentication, this should be the response hash that you generate, based on the formula required for your challenge.

ver Scalar. Optional. Protocol version supported by the client; assumed to be 0 if not specified. See Protocol Versions for details on the protocol version.

includewatchedusers Scalar. Optional. If set to 1, you will get back the list of those to whom the user has subscribed.

includewatchedby Scalar. Optional. If set to 1, you will get back the list of those who have subscribed to the user.

includetrustedusers Scalar. Optional. If set to 1, you will get back the list of those to whom the user has granted access.

includetrustedby Scalar. Optional. If set to 1, you will get back the list of those who have granted access to the user.

includecontentfilters Scalar. Optional. If set to 1, you will get back the user's list of content filters.

includetrustgroups Scalar. Optional. If set to 1, you will get back the user's list of trust groups (same as the list returned by gettrustgroups).

limit Scalar. Optional. If set to a numeric value greater than zero, this mode will only return the number of results indicated, up to a maximum set by the $LJ::MAX_WT_EDGES_LOAD variable. Applies to the trustedusers, trustedbys, watchedusers and watchedbys lists.

includebdays Scalar. Optional. If set to 1, you will also get back user birthdays with the results below.

Example Request

FIX ME: add example

Outputs

trustedusers Array of structs. Optional. If the includetrustedusers key was set, a struct with the following keys is returned for each of the trusted users (those to whom the user has granted access):

• username Scalar. Required. The username of the trusted user.
• fullname Scalar. Required. The full name of the trusted user.
• identity_type Scalar. Optional. If the trusted user's type is identity: Type of identity user, OpenID, TypeKey, etc.
• identity_value Scalar. Optional. If the trusted user's type is identity: Value for identity, OpenID is a URL.
• identity_display Scalar. Optional. If the trusted user's type is identity: Pretty display name of an identity user.
• birthday Scalar. Optional. The trusted user's birthday. This is returned only if that user has set their birthday to be publicly visible on their profile. To receive this field you will also need to request it, using the includebdays key.
• fgcolor Scalar. Required. The foreground color assigned to the trusted user.
• bgcolor Scalar. Required. The background color assigned to the trusted user.
• groupmask Scalar. Required. If the trusted user's group mask is not "1" (just bit 0 set), then this variable is returned with a 32-bit unsigned integer with bit 0 always set, and bits 1-30 set for each group this trusted user is a part of. Bit 31 is reserved.
• type Scalar. Optional. The trusted user's journal type. This value can be one of 'community', 'syndicated' or 'identity', depending on the journaltype of the account in question. The account is a normal personal account when this value is not sent.
• status Scalar. Optional. The trusted user's status. This value can be one of 'deleted', 'suspended' or 'purged', depending on the status of the account in question. The account is in the normal visible state when this value is not sent.

trustedbys Array of structs. Optional. If the includetrustedbys key was set, a struct with the following keys is returned for each of the trusting users (those who have granted access to the user):

• username Scalar. Required. The username of the trusting user.
• fullname Scalar. Required. The full name of the trusting user.
• identity_type Scalar. Optional. If the trusting user's type is identity: Type of identity user, OpenID, TypeKey, etc.
• identity_value Scalar. Optional. If the trusting user's type is identity: Value for identity, OpenID is a URL.
• identity_display Scalar. Optional. If the trusting user's type is identity: Pretty display name of an identity user.
• birthday Scalar. Optional. The trusting user's birthday. This is returned only if that user has set their birthday to be publicly visible on their profile. To receive this field you will also need to request it, using the includebdays key.
• type Scalar. Optional. The trusting user's journal type. This value can be one of 'community', 'syndicated' or 'identity', depending on the journaltype of the account in question. The account is a normal personal account when this value is not sent.
• status Scalar. Optional. The trusting user's status. This value can be one of 'deleted', 'suspended' or 'purged', depending on the status of the account in question. The account is in the normal visible state when this value is not sent.

watchedusers Array of structs. Optional. If the includewatchedusers key was set, a struct with the following keys is returned for each of the watched users (those to whom the user has subscribed):

• username Scalar. Required. The username of the watched user.
• fullname Scalar. Required. The full name of the watched user.
• identity_type Scalar. Optional. If the watched user's type is identity: Type of identity user, OpenID, TypeKey, etc.
• identity_value Scalar. Optional. If the watched user's type is identity: Value for identity, OpenID is a URL.
• identity_display Scalar. Optional. If the watched user's type is identity: Pretty display name of an identity user.
• birthday Scalar. Optional. The watched user's birthday. This is returned only if that user has set their birthday to be publicly visible on their profile. To receive this field you will also need to request it, using the includebdays key.
• fgcolor Scalar. Required. The foreground color assigned to the watched user.
• bgcolor Scalar. Required. The background color assigned to the watched user.
• groupmask Scalar. Required. If the watched user's group mask is not "1" (just bit 0 set), then this variable is returned with a 32-bit unsigned integer with bit 0 always set, and bits 1-30 set for each group this watched user is a part of. Bit 31 is reserved.
• type Scalar. Optional. The watched user's journal type. This value can be one of 'community', 'syndicated' or 'identity', depending on the journaltype of the account in question. The account is a normal personal account when this value is not sent.
• status Scalar. Optional. The watched user's status. This value can be one of 'deleted', 'suspended' or 'purged', depending on the status of the account in question. The account is in the normal visible state when this value is not sent.

watchedbys Array of structs. Optional. If the includewatchedbys key was set, a struct with the following keys is returned for each of the watching users (those who have subscribed to the user):

• username Scalar. Required. The username of the watching user.
• fullname Scalar. Required. The full name of the watching user.
• identity_type Scalar. Optional. If the watching user's type is identity: Type of identity user, OpenID, TypeKey, etc.
• identity_value Scalar. Optional. If the watching user's type is identity: Value for identity, OpenID is a URL.
• identity_display Scalar. Optional. If the watching user's type is identity: Pretty display name of an identity user.
• birthday Scalar. Optional. The watching user's birthday. This is returned only if that user has set their birthday to be publicly visible on their profile. To receive this field you will also need to request it, using the includebdays key.
• type Scalar. Optional. The watching user's journal type. This value can be one of 'community', 'syndicated' or 'identity', depending on the journaltype of the account in question. The account is a normal personal account when this value is not sent.
• status Scalar. Optional. The watching user's status. This value can be one of 'deleted', 'suspended' or 'purged', depending on the status of the account in question. The account is in the normal visible state when this value is not sent.

contentfilters Array of structs. Optional. If the includecontentfilters key was set, an array of the user's content filters is returned, listed in the order specified by each group's sortorder. A struct with the following keys is returned for each of the groups:

• id Scalar. Required. The bit number for this content filter, from 1-30.
• name Scalar. Required. The name of this content filter.
• sortorder Scalar. Required. The sort integer for this content filter, from 0-255.
• public Scalar. Required. Set to '1' if this content filter is public, otherwise set to '0'.
• data Scalar. Required. String which contains a space-separated list of the usernames in this content filter.

trustgroups Array of structs. Optional. If the includetrustgroups key was set, an array of the user's trust groups is returned, listed in the order specified by each group's sortorder. A struct with the following keys is returned for each of the groups:

• id Scalar. Required. The bit number for this trust group, from 1-30.
• name Scalar. Required. The name of this trust group.
• sortorder Scalar. Required. The sort integer for this trust group, from 0-255.
• public Scalar. Required. Set to '1' if this trust group is public, otherwise set to '0'.

Example Response

FIX ME: add example