EPIC

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
# $EPIC: userhost_function.txt,v 1.5 2006/08/30 21:02:47 sthalik Exp $
======Synopsis:======
$__userhost__() \\
$__userhost__(<nickname list>) \\
$__userhost__(<channel>)

======Technical:======
   * When used with no arguments, this function returns the userhost of the person who sent the protocol command that is currently being processed, in the bodies of, or any aliases/functions called from the bodies of:


|[[/ON ACTION]]| [[/ON CHANNEL_NICK]]| [[/ON CHANNEL_SIGNOFF]]|
|[[/ON CTCP]]| [[/ON CTCP_REPLY]]| [[/ON CTCP_REQUEST]]|
|[[/ON DCC_CHAT]]| [[/ON DCC_REQUEST]]| [[/ON ENCRYPTED_NOTICE]]|
|[[/ON ENCRYPTED_PRIVMSG]]| [[/ON EXIT]]| [[/ON FLOOD]]|
|[[/ON INVITE]]| [[/ON JOIN]]| [[/ON KICK]]|
|[[/ON KILL]]| [[/ON MODE]]| [[/ON MODE_STRIPPED]]|
|[[/ON MSG]]| [[/ON MSG_GROUP]]| [[/ON NICKNAME]]|
|[[/ON NOTE]]| [[/ON NOTICE]]| [[/ON PART]]|
|[[/ON PONG]]| [[/ON PUBLIC]]| [[/ON PUBLIC_MSG]]|
|[[/ON PUBLIC_NOTICE]]| [[/ON PUBLIC_OTHER]]| [[/ON SIGNOFF]]|
|[[/ON TOPIC]]| [[/ON WALL]]| [[/ON WALLOP]]|

   * When used with no arguments, and in any other context than the ones above, the function returns the empty string.
   * If provided with an argument, it is taken as a list of space separated nicknames.
   * The return value is a space separated list of userhosts corresponding in order to the input arguments.  If the userhost of any of the input nicknames is not known, the literal string "<UKNOWN>@<UNKNOWN>" will be provided as the userhost.
   * IT IS VERY IMPORTANT TO UNDERSTAND that the client only caches the userhosts of users who are on the same channels as you.  This command can only provide the userhosts of people who are on the same channel as you and only in the context of the same server as you.
   * This command does not block and will never launch a server query.  All answers are provided out of the channel caches.  If the client does not have the userhost for a nickname in the cache, the "UNKNOWN" userhost will be returned.
   * You must use the [[USERHOST command|USERHOST]]) command to look up the userhosts of people who are not on the same channel as you.  You may also need to use the [[USERHOST command|USERHOST]] command to look up the userhosts of people who are on the same channel as you, if you ask before [[ON CHANNEL_SYNC]] is thrown for the channel.
   * If you specify a channel name instead of a nickname list, $userhost() will return an unknown hostname, but as a side effect, it'll resolve hosts of people present on this channel.

======Practical:======
Once upon a time the server didn't give the userhost when it sent messages
to you.  When /[[ON]] was invented, userhosts weren't available and they could
not put them in $*.  Because you can't change $* in /[[ON]]s without breaking 
backwards compatibility (breaking people's scripts), $userhost() was 
created to give the new userhost information to the user.

After EPIC began caching the userhosts of people who are in the channels that
you JOIN, $userhost() started accepting nicknames.  If you ask for the userhost
of someone who isn't in a channel you are in, or if you ask before [[ON
CHANNEL_SYNC]] is thrown, then you will probably get the "UNKNOWN" userhost.
Use the [[USERHOST command|USERHOST]] command to ask the server for the
userhost in these cases.

======Returns:======
   * When used with no arguments, the userhost of the person who sent the current message (if any).
   * When used with arguments, the userhost(s) of the nickname argument(s). This uses client-side caching; the "UNKNOWN" userhost is returned if the client has not cached the userhost for a nickname(s).

======Examples:======
To show someone's address when they leave a channel:
   on ^leave "*" {
      echo *** $0 \($userhost()\) left channel $1
   }
To show another person's address on demand (must be in same channel):
   eval echo Nuke!$userhost(Nuke) writes terrible help files.
======History:======
This function originally appeared in ircII-2.1.5
Support for nickname arguments originally appeared in EPIC4pre0.027