Crate hexchat_api

This crate provides a Rust interface to the Hexchat Plugin Interface The primary object of the interface is Hexchat, which exposes an interface with functions that mirror the C functions listed on the Hexchat docs page linked above.

Macros

• dll_entry_points
  dll_entry_points() makes it very easy to set up your plugin’s DLL interface required by the Hexchat loader. This macro generates the necessary DLL entry points that Hexchat looks for when a DLL is being loaded. Normal Rust functions having the required signatures can be passed to the macro like so:
• hc_command
  Executes a command in the active Hexchat window. Provided for convenience to support formatted string commands.
• hc_command_th
  Executes a command on the main thread. This is useful for executing commands from spawned threads.
• hc_print
  Reduces the syntax required to output formatted text to the current hexchat window. Internally it invokes hexchat.print(&format!("<format-string>", arg1, arg2, ...). Using the macro, this becomes hc_print!("<format_string>", arg1, arg2, ...). To print from another thread hc_print_th!() can be used.
• hc_print_th
  Similar to hc_print!(), that can be used from spawned threads to print to the active Hexchat window. Use hc_print() if printing from the main thread.

Structs

• AsyncResult
  A result object that allows callbacks operating on a thread to send their return value to a receiver calling get() from another thread. Whether return data needs to be transferred or not, this object can be used to wait on the completion of a callback, thus providing synchronization between threads.
• Context
  Any channel in Hexchat has an associated IRC network name and channel name. The network name and channel name are closely associated with the Hexchat concept of contexts. Hexchat contexts can also be thought of as the tabs, or windows, open in the UI that have the user joined to their various “chat rooms”. To access a specific chat window in Hexchat, its context can be acquired and used. This library’s Context objects represent the Hexchat contexts and can be used to interact with the specific channels/windows/tabs that he user has open. For instance if your plugin needs to output only to specific channels, rather than the default window (which is the one currently open) - it can acquire the appropriate context using Context::find("some-network", "some-channel"), and use the object returned to invoke a command, context.command("SAY hello!"), or print, context.print("Hello!"), or perform other operations.
• EventAttrs
  Mirrors the C struct for hexchat_event_attrs. It holds the timestamps for the callback invocations for callbacks registered using hexchat_print_attrs(), and similar commands.
• Hexchat
  This struct mirrors the C Hexchat struct passed to the plugin from Hexchat when the plugin is loaded. Hexchat’s API is implemented as a struct holding callbacks to its native functions. Don’t modify this struct, unless there has been a change to the layout of it in the Hexchat C code base.
• Hook
  A wrapper for Hexchat callback hooks. These hooks are returned when registering callbacks and can be used to unregister (unhook) them. Hooks can be cloned to share a reference to the same callback hook.
• ListItem
  An eagerly constructed list item for vectors created from a ListIterator. For ThreadSafeListIterator it can sometimes be quicker to eagerly convert it to a Vec<ListItem> using ThreadSafeListIterator.to_vec() and then iterate over the resulting vector. The conversion happens on the main thread and is done all at once.
• ListIterator
  The ListIterator wraps the list pointer and related functions of Hexchat. It provides are more Rust OO interface. The iterator returns clones of itself that can be used to access the current list item’s fields through get_field(). The list iterator object is internally a smart pointer, among other things. You can clone it if you need multiple references to a list.
• Plugin
  Represents a created plugin entry. Plugins that embed other language interpreters and load plugins written in those languages can have Hexchat look as if the loaded scripts are actual plugins. By creating a Plugin object for such a script, an entry is made in Hexchat’s list of loaded plugins. When one of these scripts is unloaded, the fictitious plugin entry can be removed from Hexchat by dropping the associated Plugin object.
• PluginInfo
  Hexchat addons need to return an instance of this struct from their plugin_info() function, which gets called when Hexchat loads the addons. The PluginInfo object holds pinned internal buffers that Hexchat can read from at its leisure.
• ThreadSafeContext
  A thread-safe version of Context. Its methods automatically execute on the Hexchat main thread. The full set of methods of Context aren’t fully implemented for this struct because some can’t be trusted to produce predictable results from other threads. For instance .set() from a thread would only cause Hexchat to momentarily set its context, but Hexchat’s context could change again at any moment while the other thread is executing.
• ThreadSafeHexchat
  A thread-safe wrapper for the Hexchat object. It implements a subset of the methods provided by the wrapped object. A lot of methods don’t make sense to expose; those that do should provide enough utility to code that needs to invoke Hexchat from other threads.
• ThreadSafeListIterator
  A thread-safe wrapper class for the Hexchat ListIterator. The methods provided, internally execute on the Hexchat main thread without any additional code necessary to make that happen in the client code.

Enums

• ChanFlag
  Channel flags.
• ChanType
  Channel types.
• DccStatus
  DCC status values.
• DccType
  DCC action type.
• Eat
  The return value for client plugin callbacks.
• FD
  File descriptor types.
• FieldValue
  Field Data Types
• HexchatError
  Each of the various ways the API can fail is collected in this enumerated type.
• IgnFlag
• PrefValue
  Represents the values that can be accessed using the prefs functions of the Hexchat object (hc.pluginpref_get(), hc.pluginpref_get(), etc.). The enumeration enables the typing of the values stored and retrieved.
• Priority
  The priorty for a given callback invoked by Hexchat.
• StripFlags
  Used by the hexthat.strip() function to determine what to strip from the target string.
• ThreadSafeFieldValue
  Thread-safe versions of the FieldValue variants provided by ListIterator.
• UserData
  Represents the user data that is provided to callbacks when they’re invoked. A UserData object is registered with the callback using one of the hook commands. The user data can be virtually any type that implements the Any trait capable of being downcast to its original type. There are four variants for the user data. Which one to use depends on how the callback user data is shared. If the data is unique to one callback, then BoxedData should be enough. For single threaded sharing among more than one callback, SharedData will do the trick. If, for any odd sort of reason threading somehow becomes relevant to the user data object, SyncData would be the variant to use.

Constants

• IRC_BEEP
• IRC_BLACK
• IRC_BOLD
• IRC_CYAN
• IRC_GRAY
• IRC_GREEN
• IRC_HIDDEN
• IRC_ITALICS
• IRC_LIGHT_GRAY
• IRC_LIGHT_GREEN
• IRC_MAGENTA
• IRC_MAROON
• IRC_NAVY
• IRC_OLIVE
• IRC_ORIG_ATTRIBS
• IRC_PURPLE
• IRC_RED
• IRC_REVERSE_COLOR
• IRC_ROYAL_BLUE
• IRC_TEAL
• IRC_UNDERLINE
• IRC_WHITE
• IRC_YELLOW

Functions

• main_thread
  Executes a closure from the Hexchat main thread. This function returns immediately with an AsyncResult object that can be used to retrieve the result of the operation that will run on the main thread.
• turn_off_threadsafe_features^⚠Deprecated
  Stops and removes the main thread task queue handler. Otherwise it will keep checking the queue while doing nothing useful - which isn’t necessarily bad. Performance is unaffected either way.

Type Aliases

• DeinitFn
  The signature for the deinit function plugin authors need to register using dll_entry_points!().
• InfoFn
  The signature of the info function plugin authors need to register using dll_entry_points!().
• InitFn
  The signature for the init function that plugin authors need to register using dll_entry_points!().