xchat-plugin-0.0.3: XChat

Safe HaskellSafe-Infered

Network.IRC.XChat.Plugin

Contents

Synopsis

Documentation

This is my first binding in Haskell (and in any other language btw), so I probably lack of good practice.

I tried to do bindings for the XChat plugin system, but some functions were not documented (these are tagged [Undocumented]), those function are expect to have their signature changed once they become documented (and I understand what they truly are for). For these functions, I would gladly accept some enlightment of what they really do.

For the other functions, I would also accept advice on how to improve the binding.

There are also some lacking functions:

  • xChatPrintF (special case of xChatPrint)
  • xChatCommandF (special case of xChatCommand)
  • xChatFree (automatically called)
  • all functions on lists but the xChatGetList specialized in 5 versions

To contact me: sed?rikov@gma?il.com (remove the question marks) For more information, read the README.txt file

Functions

data PluginDescriptor Source

The plugin descriptor

data XChatPlugin a Source

The type of plugins; it is associated to a memory which can be used and modified by the hooked callbacks.

All the following functions needs a XChatPlugin as argument. In fact it is a handle which needs to be initialized by the init function, and will be freed by an optional deinit function.

xChatPluginInit :: Ptr (XchatPlugin a) -> a -> IO (XChatPlugin a)Source

The plugin initializer. NEVER call it, it is only used by hsxchat.

The Lists

All XChat informations are stored in lists. There are 5 lists, each of them having its own section for a further description.

To get access to such a list, you have to request it from XChat, using the provided function. There is no magic you have to get the list each time you have get informations, since it may have changed since the last time.

Channels

data ChanFlgs Source

Constructors

ChanFlgs 

Fields

connected :: Bool

Already connected

connecting :: Bool

Connecting in progress

away :: Bool

You are away

logged :: Bool

Login complete

whox :: Bool

Has WHOX (ircu)

idmsg :: Bool

Has IDMSG (FreeNode)

jPmsg :: Bool

Hide Join/Part messages unused flag not figuring in the ChanFlgs

beep :: Bool

Beep on message

blinkTray :: Bool

Blink tray

blinkTask :: Bool

Blink task bar

data Chan Source

Constructors

Chan 

Fields

cChannel :: String

Channel or query name

cChantypes :: String

Channel type e.g. "#!&"

cContext :: XChatContext

Context of the channel

cFlags :: ChanFlgs

Server/Channel bits

cId :: Int32

Unique server ID

cLag :: Int32

Lag in milliseconds

cMaxmodes :: Int32

Maximum modes per line

cNetwork :: String

Network name of the channel

cNickprefixes :: String

Nickname prefixes e.g. "@+"

cNickmodes :: String

Nickname mod chars e.g. "ov"

cQueue :: Int32

Number of bytes in send-queue

cServer :: String

Server name of the channel

cType :: ChanType

Type of context

cUsers :: Int32

Number of users in the channel

DCC

data Dcc Source

Constructors

Dcc 

Fields

dAddress32 :: Int32

ipv4 address of remote user (dunno how to have ipv6)

dCps :: Int32

Bytes per seconds

dDestfile :: String

Destination full pathname

dFile :: String

File name

dNick :: String

Nickname of the person who the file is from/to (Receive/Send mode)

dPort :: Int32

TCP port number

dPos :: Int32

Bytes send/received up to now for the current transfert

dResume :: Int32

Offset of file from which it is resumed (0 if not resumed)

dSize :: Int64

File size in bytes

dStatus :: DccStatus

Status of the DCC transfert

dType :: DccType

Type of the DCC transfert

Ignore

data IgnFlgs Source

Constructors

IgnFlgs 

Fields

private :: Bool
 
notice :: Bool
 
channel :: Bool
 
ctcp :: Bool
 
invite :: Bool
 
unIgnore :: Bool
 
noSave :: Bool
 
dcc :: Bool
 

data Ign Source

Constructors

Ign 

Fields

iMask :: String

Ignore mask. .e.g: *!*@*.aol.com

iFlags :: IgnFlgs

Flags

Notify

data Notify Source

Constructors

Notify 

Fields

nNetworks :: [String]

Networks to which this nick applies

nNick :: String

Nickname

nOnline :: Bool

Currently on-line

nOn :: Int32

Time when nick came online

nOff :: Int32

Time when nick went offline

nSeen :: Int32

Time when nick was last seen

Users

data User Source

Constructors

User 

Fields

uAway :: Bool

Away status

uLasttalk :: Int32

Last time when user talked

uNick :: String

Nickname

uHost :: Maybe String

Host name, user@host

uPrefix :: String

e.g. @ or +

uRealname :: Maybe String

Real name

uSelected :: Bool

If user belongs to the focused tab

The hooks system

All XChatHooks returned can be passed to xChatUnhook. This is not mandatory, as they are automatically unhooked at unloading time. All hooks return a Hook a b c type.

The hook system is not exactly the one used in the original C/C++ library. In the original library, some memory was attached to each hook, but that meant that shared memory had to be done through pointers. Now all functions of the original library are given the same plugin memory pointer, and this memory is attached to the plugin itself, so all hooking functions are only given a XChatPlugin (which internally contains a memory) and its memory is not explicitly given anymore at hooking time.

Types

data XChatHook a b c Source

The type of hooks; it has three type arguments.

  • The first is the type of the plugin memory
  • The second one is the type returned at hook creation, it can be used to restore the memory at unhooking time, or to print some debugging information.
  • The third one is the type returned at unhooking time, it can be used to display debugging information.

data Eating Source

The way callbacks are managed; a callback function can be eat an event, that is make the event unprocessable, either to XChat or to the other plgins.

Constructors

Eating 

Fields

eatXChat :: Bool
 
eatPlugin :: Bool
 

type Hook a b c d = XChatPlugin a -> (d -> a -> IO (Eating, a)) -> (a -> IO (b, a)) -> IO (b, XChatHook a b c)Source

The returned type of all hooking functions; if f is a Hook a b c d hooking function, then:

      f ph cb init

means that a new XChatHook a b c hook using the callback cb function is created for the ph plugin; the hooking modifies the a plugin memory according to init, and returns the b returned by init as well as the created hook.

The callback function itself is a function which takes some d data, the a plugin memory at the moment when the callback function is called and returns how the event which triggered the callback call is eaten as well as the new a plugin memory.

data PriorityC Source

a concrete type to define the priority of a command

Constructors

Highest

Highest priority (127)

High

High priority (64)

Norm

Normal priority (0)

Low

Low priority (-64)

Lowest

Lowest priority (-128)

Custom Int32

Custom, is normalized when cast to PriorityA

data PriorityA Source

an abstract type to define the priority of a command

abstractPriority :: PriorityC -> PriorityASource

to get a (normalized) abstract priority from a concrete one

concretePriority :: PriorityA -> PriorityCSource

to get a concrete priority from an abstract one

data Flags Source

flags for file descriptors

Constructors

Flags 

Fields

fgRead :: Bool
 
fgWrite :: Bool
 
fgExn :: Bool
 
fgNsock :: Bool
 

Hooks

xChatHookCommand :: String -> PriorityA -> Maybe String -> Hook a b c StringSource

xChatHookCommand cmd pri help

Description:

Hooking to the /cmd input box command at priority pri with an optional help message.

To capture text without a '/' at the start (non-commands), you may hook a special name of "" as in:

let eatAll           = Eating { eatXChat = True, eatPlugin = True }
    startWithYou s a = xChatPrint p ("you: "++s) >> return (eatAll, a)
in  xChatHookCommand "" Norm Nothing p startWithYou ()

which automatically adds "you: " at the beginning of each sentence you type (and is undocumented as the help message argument is Nothing).

Commands hooked that begin with a period ('.') will be hidden in /HELP and /HELP -l.

Arguments:

cmd
The command (without the forward slash) with some special treatment if it is the empty string or if it begins with a dot
pri
Priority of the hook, you should probably use Norm
help
Optionnal help message, displayed at /HELP cmd command

Callback Function Main Argument:

The callback function expects a string containing all the arguments passed to the command.

xChatHookServer :: String -> PriorityA -> Hook a b c StringSource

Description:

xChatHookServer ev pri

Hooking to the server event ev at priority pri.

To capture all server events, use "RAW LINE".

Arguments:

ev
The server event to be captured
pri
Priority of the hook, you should probably use Norm

Callback Function Main Argument:

The callback function expects a string containing all the arguments of the captured server event.

xChatHookPrint :: String -> PriorityA -> Hook a b c [String]Source

Description:

xChatHookPrint prev pri

Hooking to the print event prev at priority pri.

Available events are those in "Advanced > Text Events" plus these ones:

"Open Context"
Called when a new XChatContext is created.
"Close Context"
Called when a xchat_context pointer is closed.
"Focus Tab"
Called when a tab is brought to front.
"Focus Window"
Called a toplevel window is focused, or the main tab-window is focused by the window manager.
"DCC Chat Text"
Called when some text from a DCC Chat arrives. It provides these arguments for the callback function: [_, Address, Port, Nick, The Message]
"Key Press"
Called when some keys are pressed in the input-box. It provides these arguments for the callback function: [_, Key Value, State Bitfield (shift, capslock, alt), String version of the key, Length of the string (may be 0 for unprintable keys)]

Arguments:

prev
The print event to be captured
pri
Priority of the hook, you should probably use Norm

Callback Function Main Argument:

The callback function expects a list of strings containing all the arguments of the captured print event.

xChatHookTimer :: Int32 -> Hook a b c ()Source

Description:

xChatHookTimeout timeout

Hooking to call a function every timeout milliseconds.

Arguments:

timeout
The time(ms) to wait before the next triggering of the callback.

Callback Function Main Argument:

The callback function expects just a unit type.

xChatHookFd :: Fd -> Flags -> Hook a b c (Fd, Flags)Source

Description:

xChatHookFd fd flgs

Hooking to the file descriptor fd with flags flgs. The callback function is called every time the file descriptor is available to an action described by the flags.

Arguments:

fd
The file descriptor or socket
flgs
The flags of the file descriptor

Callback Function Main Argument:

The callback function expects a file descriptor and a flag (that may be removed in a newer version).

Removing hooks

xChatUnhook :: XChatPlugin a -> XChatHook a b c -> (a -> IO (c, a)) -> IO cSource

Description:

xChatUnhook ph hook restore

Unhooking of the given hook. According to the xchat plugin documentation, hooks are automatically removed at deinit time. But you may wish for some reason to hook or unhook dynamically some function. There is an argument that allows you to modify the memory at unhook time. For example, if you have a counter, your memory could be a Maybe Int. When you hook, you may want to put it Just 0 and when you unhook to put it back to Nothing.

Arguments:

ph
The plugin handle of which we want to unhook.
hook
The hook to remove from the plugin.
restore
The function to be called on the memory of the plugin.

Contexts

Contexts are mainly a tab+window pair. I do not know more as the original documentation is rather sparse on it.

You have 3 functions on contexts (find, get and set).

The xChatHookPrint can detect opening and closing of contexts.

data XChatContext Source

the type of contexts

xChatSetContext :: XChatPlugin a -> XChatContext -> IO BoolSource

Description:

xChatSetContext ph ctx

Changes the current context.

Arguments:

ph
Plugin handle whose context is to be changed.
ctx
Context (given by xChatGetContext or xChatFindContext).

Returns:

True if successful, False else.

xChatFindContext :: XChatPlugin a -> Maybe String -> Maybe String -> IO XChatContextSource

Description:

xChatFindContext ph servname channel

Finds a context based on a channel and servername.

If servname is Nothing, it finds the channel (or query) by the given name in the same server group as the current context. If that doesn't exists then find any by the given name.

If channel is Nothing, it finds the front-most tab/window of the given servname.

Arguments:

ph
Plugin handle.
servname
Servername.
channel
Channelname.

Returns:

Context (for use with xChatSetContext).

xChatGetContext :: XChatPlugin a -> IO XChatContextSource

Description:

xChatGetContext ph

Get the current context.

Arguments:

ph
Plugin handle whose context is to be taken.

Returns:

The current context.

Some other commands

xChatPrint :: XChatPlugin a -> String -> IO ()Source

Description:

xChatPrint ph text

Displays some text in the xchat window.

Arguments:

ph
The plugin handle which manages the printing.
text
The text to display. May contain mIRC color codes.

xChatCommand :: XChatPlugin a -> String -> IO ()Source

Description:

xChatCommand ph cmd

Executes a command as if it were typed in xchat's input box.

Arguments:

ph
The plugin handle which manages the command.
text
The command to execute without the heading '/'.

xChatNickcmp :: XChatPlugin a -> String -> String -> IO OrderingSource

Description:

xChatNickcmp ph s1 s2

Performs a nick name comparision, based on the current server connection. This might be a RFC1459 compliant string compare, or plain ascii (in the case of DALNet). Use this to compare channels and nicknames. The function works the same way as strcasecmp.

Quote from RFC1459:

Because of IRC's scandanavian origin, the characters {}| are considered to be the lower case equivalents of the characters []\, respectively. This is a critical issue when determining the equivalence of two nicknames.

Arguments:

ph
Plugin handle whose context is to be taken.
s1
1st string to compare
s2
2nd string to compare

Returns:

The comparison of the two strings.

data SettingResult Source

The result of a setting request

xChatGetPrefs :: XChatPlugin a -> String -> IO SettingResultSource

Description:

xChatGetPrefs ph pref

Provides xchat's setting information (that which is available through the "/set" command). A few extra bits of information are available that don't appear in the "/set list", currently they are:

state_cursor
Current input-box cursor position (characters, not bytes).
id
Unique server id.

Arguments:

ph
Plugin handle.
pref
Setting name required.

Returns:

A failure, a String, a Bool or an Int32 according to the SettingResult case.

xChatGetInfo :: XChatPlugin a -> String -> IO (Maybe String)Source

Description:

xChatGetInfo ph info

Returns information based on your current context.

Arguments:

ph
Plugin handle.
id
ID of the information you want. Currently supported IDs are (case sensitive):
  • [away] away reason or Nothing if you are not away.
  • [channel] current channel name.
  • [charset] character-set used in the current context.
  • [event_text] text event format string for name.
  • [host] real hostname of the server you connected to.
  • [inputbox] the input-box contents, what the user has typed.
  • [libdirfs] library directory. e.g. /usr/lib/xchat. The same directory used for auto-loading plugins. This string isn't necessarily UTF-8, but local file system encoding.
  • [modes] channel modes, if known, or Nothing.
  • [network] current network name or Nothing.
  • [nick] your current nick name.
  • [nickserv] nickserv password for this network or Nothing.
  • [server] current server name (what the server claims to be). Nothing if you are not connected.
  • [topic] current channel topic.
  • [version] xchat version number.
  • [win_ptr] native window pointer. Unix: (GtkWindow *) Win32: HWND.
  • [win_status] window status: "active", "hidden" or "normal".
  • [xchatdir] xchat config directory, e.g.: /home/user/.xchat2 This string is encoded in UTF-8, which means you _should_ convert it to "locale" encoding before using functions like open() or OpenFile(). For best Unicode support on Linux, convert this string using g_filename_from_utf8 and on Windows convert this string to UTF-16LE (wide) and use OpenFileW() etc.
  • [xchatdirfs] xchat config directory, e.g.: /home/user/.xchat2. This string is encoded in local file system encoding, making it ideal for direct use with functions like open() or OpenFile(). For real Unicode support on Windows, it's best not to use xchatdirfs, but xchatdir instead.

Returns:

A string of the requested information, or Nothing.

xChatEmitPrint :: XChatPlugin a -> String -> [String] -> IO BoolSource

Description:

xChatEmitPrint ph ev args

Generates a print event. This can be any event found in the Preferences > Advanced > Text Events window. The args are the arguments of the event. Special care should be taken when calling this function inside a print callback (from xChatHookPrint), as not to cause endless recursion.

Arguments:

ph
Plugin handle.
ev
Text event to print.
args
Arguments of the event to print.

Returns:

True in case of success False else.

Example:

xChatEmitPrint "Channel Message" ["John", "Hi there", "@"]

xChatSendModes :: XChatPlugin a -> [String] -> Maybe Int32 -> Bool -> Char -> IO ()Source

Description:

xChatSendModes ph str_list mpl sgn mode Sends a number of channel mode changes to the current channel. For example, you can Op a whole group of people in one go. It may send multiple MODE lines if the request doesn't fit on one. Pass Nothing for mpl to use the current server's maximum possible. This function should only be called while in a channel context.

Arguments:

ph
The plugin handle
str_list
The targets
mpl
The number of modes per line
sgn
The sign (True is '+', False is '-')
mode
The mode char, e.g. 'o' for Ops

Example:

xChatSendModes "Alice":"Bob":[] 3 True 'o'

data StripRules Source

flags on how to strip rules

Constructors

StripRules 

Fields

noColor :: Bool
 
noAttribute :: Bool
 

xChatStrip :: String -> StripRules -> IO StringSource

Description:

xChatStrip str rules

Strips mIRC color codes and/or text attributes (bold, underlined etc) from the given string and returns a new string. The original function had an unused plugin handle.

Arguments:

str
The string to strip
rules
The description of the plugin to add

Undocumented

xChatPluginguiAdd :: XChatPlugin a -> String -> PluginDescriptor -> IO (XChatPlugin a)Source

Undocumented

Description:

xChatPluginguiAdd ph filename pdesc

Add of a new GUI plugin to the list of the current plugins. Due to lack of documentation, it is not further documented. In the original source code, such added plugins are tagged 'fake'. It seems that beside their name, file name, version, description and position in the list, there is no memory allocation. Furthermore, the original code had an extra unused argument.

Arguments:

ph
The plugin handle to be used by default if the USE_PLUGIN directive was not given at compile time for XChat, if the USE_PLUGIN directive was provided, a new plugin handle is created, with the data of [ph] passed by
filename
The path name of the file containing the plugin to add
pdesc
The description of the plugin to add

xChatPluginguiRemove :: XChatPlugin a -> IO ()Source

Undocumented

Description:

xChatPluginguiRemove ph

The counterpart of xChatPluginguiAdd function. So it is used to remove 'fake' plugins. Once again, one of the arguments is unused in the original source code, so I removed it.

Arguments:

ph
The plugin handle to be removed

xChatGettext :: String -> IO StringSource

Undocumented

Description:

xChatGettext str

Converts a string to its internal XChat representation. I automatically free it to avoid memory leak, although as I don't know what it really does, it may be a bad idea. The original code had an unused plugin handle.

Arguments:

str
The string to convert