RGTP stands for Reverse Gossip Transfer Protocol. An RGTP board, such as GROGGS, consists essentially of a set of "items", each denoted by an eight-character itemid such as "A1240111". An item consists of a sequence of posts on a given subject, identified by a subject string attached to the item. When an item has reached a certain size, attempting to post to it will instead generate a new item, known as a "continuation" or "child" item, with a new itemid and subject string. RGTP keeps track of which items are children of which parent items, thus allowing long chains of discussion to be built.

The first character of itemids was "A" in 1986, the first year of GROGGS's existence, and has been incremented through the alphabet every year since. (The letter for 2005 is "U".)

Every user is identified to RGTP by their email address. They are usually identified to the other users by a string known as their "grogname". (These are usually fanciful, and regular contests are held as to the best ones.)

Every action which causes a state change on an RGTP server is given a monotonically increasing sequence number. Most actions are also given timestamps. These are in seconds since midnight UTC, 1 January 1970.

USERID is the user identity to use on the RGTP server, typically an email address. If left blank it will default to "guest".

SECRET is the shared-secret which is sent out by mail. It must either be a hex string with an even number of digits, or undef. It should be undef only if you are expecting not to have to go through authentication (for example, on many RGTP servers the account called "guest" needs no authentication step).

This method returns the current access level, in the format returned by the access_level method. The method returns undef on failure, and sets $@ to an appropriate message.

Returns the current access level. 0 means only the message of the day may be read. 1 means the index and any item may be read, but nothing may be written. 2 means that items may be posted to. 3 means that the contents of the items, including posts made by other users, may be edited.

Similar to the item method, but the hashref returned does not contain the key posts. Use this method if you only need to know, for example, the item's most recent sequence number or its subject line. It executes many times faster than the item method, because the content of the item does not need to be transferred.

This implements the RGTP function "STAT". The method is not called stat because that is a perl builtin.

The keys of the hashref are the itemids of the several items, except for the key "motd", which describes the message of the day. Each key maps to a hash describing the item. The keys of this hash are:

subject: the subject line of the item. This may be truncated by the RGTP server; you may find the exact subject line using the item method.

posts: a count of posts.

timestamp: the timestamp of the most recent change to this item.

seq: the sequence number of the most recent change to this item.

parent: the itemid of the parent of this item. Exists only for items which have a parent.

child: the itemid of the child of this item. Exists only for items which have a child.

This method may take a long time to execute on popular RGTP servers the first time it is called. This is because it has to download the entire index. Subsequent calls will use cached data and will be faster. See also the state method.

This method exists because the items method is slow on first use. (Over my home connection, for the main GROGGS server, it takes about forty seconds). When called with no arguments, state returns a scalar describing the state of items's cache. When called with this scalar as argument, it re-fills the cache with this data. This scalar can be seralised so that the advantages of caching can be gained between sessions.

Items have a maximum size. Thus after a certain amount of posting to any given item, it will cease to be possible to post any more content. When this happens, post will return undef, and set the "continuation flag", which may be inspected using the item_is_full method.

When the flag is set, and only when the flag is set, it is possible to call post again with the WHERE parameter set to "continue". This creates a continuation item following on from the item you were originally trying to post to.

Because RGTP is not threaded, most users want to check, when they reply to an item, that it has not been replied to already while they were composing their reply. The lack of a built-in way to do this is a fundamental flaw in RGTP; most clients get around the problem by doing a STAT (equivalent to our quick_item method) immediately before posting, and comparing the sequence number given to one taken before the reply was composed. Net::RGTP provides an easy way to accomplish this: setting the Seq option to the post command. If this check fails, post will return undef and item_has_grown will subsequently return true.

However, any such mechanism introduces a race condition into the protocol. The chance of a race occurring is slight, and the problems caused thereby are small, but programmers should be aware of it.

The only case when RGTP does tell us when an item has been updated is when an item has gone into a continuation. In this case post and item_has_grown will behave as if Seq had been specified, even if it was not.