getusertags

getusertags — Retrieves a list of the user's defined tags.

Mode Description

Retrieves a list of the user's defined tags.

Arguments

mode

The protocol request mode: getusertags

user

Username. Leading and trailing whitespace is ignored, as is case.

auth_method

The authentication method used for this request. Default is 'clear', for plain-text authentication. 'cookie' or any of the challenge-response methods are also acceptable.

password

Deprecated. Password in plain-text. For the default authentication method, either this needs to be sent, or hpassword.

hpassword

Deprecated. Alternative to plain-text password. Password as an MD5 hex digest. Not perfectly secure, but defeats the most simple of network sniffers.

auth_challenge

If using challenge-response authentication, this should be the challenge that was generated for your client.

auth_response

If using challenge-response authentication, this should be the response hash you generate based on the challenge's formula.

ver

(Optional) Protocol version supported by the client; assumed to be 0 if not specified. See Chapter 27, Protocol Versions for details on the protocol version.

usejournal

(Optional) If you want to get the tags for a community you're a member of, include this key and the username of the account to get the tags of. By default, you get your own tags.

Return Values

success

OK on success or FAIL when there's an error. When there's an error, see errmsg for the error text. The absence of this variable should also be considered an error.

errmsg

The error message if success was FAIL, not present if OK. If the success variable is not present, this variable most likely will not be either (in the case of a server error), and clients should just report "Server Error, try again later.".

tag_count

The number of tags being returned in this set. The number is base-1, so start at 1 and count up to this number inclusive in order to make sure you get all of the tags. If this value is 0, there are no tags for the specified account.

tag_num_name

The tag itself, this is the name to be sent when you're posting or editing an entry. Textual representation of the tag.

tag_num_uses

(Optional) Indicates how many times this tag has been used. May not be present, which indicates no usage of the tag.

tag_num_display

(Optional) If present and on, indicates that this tag is displayed on a user's list of tags. A tag that is not displayed is hidden from the S2 style system, but is otherwise available for use.

tag_num_security

The security level of this tag. This indicates who can see the tag and the entries tagged with it. Security can be one of 'public', 'private', 'friends', and 'group'. Note that 'group' secure tags do not elaborate on which groups they're secured to, but that can be inferred from the security breakdown section.

tag_num_sb_friends

(Optional) If present, indicates the number of times this tag has been used on Friends-only entries.

tag_num_sb_public

(Optional) If present, indicates the number of times this tag has been used on public entries.

tag_num_sb_private

(Optional) If present, indicates the number of times this tag has been used on public entries.

tag_num_sb_group_count

(Optional) If present, indicates the number of groups that are using this tag. This number can then be used in a loop (from 1 to this number inclusive) to get the actual groups this tag has been used on.

tag_num_sb_group_num_id

The id of the group this tuple is about. This has a 1:1 mapping with the frgrp_num in getfriendgroups.

tag_num_sb_group_num_count

The number of times this tag has been used on this group.