Site Tools


userhost_command
no way to compare when less than two revisions

Differences

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


userhost_command [2007/02/02 23:17] (current) – created - external edit 127.0.0.1
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 by 127.0.0.1