Site Tools


userhost_command

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

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-)
 +      }
 +
  
userhost_command.txt ยท Last modified: 2007/02/02 23:17 (external edit)