This shows you the differences between two versions of the page.
— |
userhost_command [2007/02/02 23:17] (current) |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ======Synopsis:====== | ||
+ | __userhost__ [-direct] [-count <number>] [-extra <stuff>] [<nickname> [<nickname> ...] [-cmd <command>]] | ||
+ | |||
+ | ======Description:====== | ||
+ | This asks the server for the address (user@hostname) of each of the | ||
+ | specified nicknames. You may query as many nicknames as you wish, | ||
+ | however the irc protocol limits any one request to 5 nicknames; the client | ||
+ | will break your list into groups of 5 and request each group separately. | ||
+ | If you query too many nicknames, you may flood yourself off the server. | ||
+ | |||
+ | If you specify the **-cmd** option, then anything that follows that | ||
+ | option will be taken as a [[block]] that shall be executed for each and | ||
+ | every nickname in the list **IN THE SAME ORDER AS THE LIST**. If any of | ||
+ | the nicknames in the list are not on irc, a placeholder userhost will be | ||
+ | passed to the -cmd block in that nickname's turn. (further described below) | ||
+ | |||
+ | ======About asynchronous behavior:====== | ||
+ | The traditional behavior of USERHOST was to execute the -cmd option | ||
+ | asynchronously. Asynchronous execution means that execution of code | ||
+ | is postponed until the future, when the server replies to the query. | ||
+ | When USERHOST behaves asynchronously, the USERHOST command simply submits | ||
+ | a request for userhosts to the server and returns immediately. The -cmd | ||
+ | option will not have been executed -- not even once -- and will not be | ||
+ | executed until the next time EPIC checks for data from the server. | ||
+ | |||
+ | ======About synchronous behavior:====== | ||
+ | However, if all of the nicknames in the list are present in the client's | ||
+ | internal userhost cache, then this command behaves synchronously. The | ||
+ | -cmd option will be executed for **all** nicknames in the list **before** | ||
+ | **the USERHOST command returns.** If you do not want this behavior, you | ||
+ | can use the **-direct** option to force __USERHOST__ to send the request | ||
+ | to the server instead of looking in the cache. | ||
+ | |||
+ | However, EPIC cannot cache the "away status" or "oper status" that is | ||
+ | provided by a userhost request and whenever it behaves synchronously, the | ||
+ | away status and oper status will be wrong. If you need the away status or | ||
+ | oper status, you should use the **-direct** option to get this information | ||
+ | from the server. | ||
+ | |||
+ | The use of the [[wait]] command arranges for synchronous behavior after | ||
+ | the execution of an asynchronous command. | ||
+ | |||
+ | ======Extra data:======= | ||
+ | Sometimes you want to pass extra data to the **-cmd** callback, and because | ||
+ | of the asynchronous behavior of [[userhost]], it's difficult to arrange this | ||
+ | without [[wait]]ing. The [[userhost]] command supports an **-extra** flag | ||
+ | that takes a variable name and saves the contents of that variable at the | ||
+ | time you do the request, and then appends that value when the userhost | ||
+ | callbacks are executed. The variable is only used at the time you make the | ||
+ | userhost request, so you can change it (or use a local variable) and that | ||
+ | won't affect the value passed to the callbacks. | ||
+ | |||
+ | The extra data is appended to $* in the /on 303 numeric as well. | ||
+ | |||
+ | ======Options:====== | ||
+ | | -direct |Require __userhost__ to query the server. | | ||
+ | | -cmd |Pass the output from __userhost__ as input to other commands: | | ||
+ | | -count |Maximum number of nicks EPIC will query for in every request | | ||
+ | | -extra |Add the contents of a variable to the callback data | | ||
+ | |||
+ | __USERHOST__ passes the following arguments to -cmd: | ||
+ | |||
+ | $0 - nickname | ||
+ | $1 - a '+' if the user is an irc operator, a '-' otherwise | ||
+ | $2 - a '+' if the user is marked as away, a '-' otherwise | ||
+ | $3 - username | ||
+ | $4 - hostname | ||
+ | $5- - The extra data, if any. | ||
+ | |||
+ | ======Examples:====== | ||
+ | To get the userhosts of JoeBob and Jimbo: | ||
+ | /userhost joebob jimbo | ||
+ | |||
+ | To use their userhost output as another command's input in a script: | ||
+ | userhost joebob jimbo -cmd { | ||
+ | echo $0 is $3@$4 | ||
+ | if ( [$1] == [+] ) echo $0 is an irc operator | ||
+ | if ( [$2] == [+] ) echo $1 is away | ||
+ | } | ||
+ | |||
+ | To pass extra data to a userhost callback: | ||
+ | @ var = [This is" a compli\cat\\ed string"] | ||
+ | userhost -extra var joebob jimbo -cmd { | ||
+ | xecho -b $0 is $3@$4 ($5-) | ||
+ | } | ||
+ | |||