Struct hexchat_api::Hexchat

#[repr(C)]
pub struct Hexchat { /* private fields */ }

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.

Implementations

impl Hexchat

This is the rust-facing Hexchat API. Each method has a corresponding C function pointer which they wrap and marshal data/from.

pub fn threadsafe(&self) -> ThreadSafeHexchat

Returns a thread-safe wrapper for Hexchat that exposes thread-safe methods wrapping several of Hexchats methods.

pub fn print(&self, text: &str)

Prints the string passed to it to the active Hexchat window.

Arguments

• text - The text to print.

pub fn command(&self, command: &str)

Invokes the Hexchat command specified by command.

Arguments

• command - The Hexchat command to invoke.

pub fn hook_command<F>( &self, name: &str, pri: Priority, callback: F, help: &str, user_data: UserData ) -> Hookwhere F: FnMut(&Hexchat, &[String], &[String], &UserData) -> Eat + 'static,

Registeres a command callback with Hexchat. This will add a user invocable slash “/” command that can be seen when listing /help. The callback can be a static function, or a closure, that has the form:

    FnMut(&Hexchat, &[String], &[String], &UserData)
    -> Eat

Note that the callback parameters include a reference to the Hexchat object as a convenience. This differs from the C interface which doesn’t include it.

Arguments

• name - The name of the event that invokes the callback.
• pri - The priority of the callback.
• callback - The static function or closure to register.
• help - Help text displayed by Hexchat for the command.
• user_data - Data passed back to the callback when invoked.

Returns

A Hook object associated with the callback.

pub fn hook_server<F>( &self, name: &str, pri: Priority, callback: F, user_data: UserData ) -> Hookwhere F: FnMut(&Hexchat, &[String], &[String], &UserData) -> Eat + 'static,

Registers a callback to be called when a certain server event occurs. For any of these functions, more information can be found at Hexchat Plugin Interface The callback needs to be compatible with this signature:

FnMut(&Hexchat, &[String], &[String], &UserData)
-> Eat

Arguments

• name - The name of the event to listen for.
• pri - The priority of the callback.
• callback - The callback to invoke when the event occurs.
• user_data - The user data that gets passed back to the callback when it’s invoked.

Returns

• A Hook object that can be used to deregister the callback. It doesn’t need to be retained if not needed.

pub fn hook_print<F>( &self, event_name: &str, pri: Priority, callback: F, user_data: UserData ) -> Hookwhere F: FnMut(&Hexchat, &[String], &UserData) -> Eat + 'static,

Registers a callback to be called when a given print event occurs. This can be any of the text events listed under Settings > Text Events. Callback needs to be compatible with this signature:

FnMut(&Hexchat, &[String], &UserData) -> Eat

Arguments

• name - The name of the event to listen for.
• pri - The priority of the callback.
• callback - The callback to invoke when the event occurs.
• user_data - The user data that gets passed back to the callback when it’s invoked.

Returns

• A Hook object that can be used to deregister the callback. It doesn’t need to be retained if not needed.

pub fn hook_print_attrs<F>( &self, name: &str, pri: Priority, callback: F, user_data: UserData ) -> Hookwhere F: FnMut(&Hexchat, &[String], &EventAttrs, &UserData) -> Eat + 'static,

Registers a callback to be called when a given print event occurs. The callback will be invoked with an EventAttrs object containing a time_t value for the event. The callback needs to be compatible with this signature:

FnMut(&Hexchat, &[String], &EventAttrs, &UserData)
-> Eat

Arguments

• name - The name of the event to listen for.
• pri - The priority of the callback.
• callback - The callback to invoke when the event occurs.
• user_data - The user data that gets passed back to the callback when it’s invoked.

Returns

• A Hook object that can be used to deregister the callback. It doesn’t need to be retained if not needed.

pub fn hook_timer<F>( &self, timeout: i64, callback: F, user_data: UserData ) -> Hookwhere F: FnMut(&Hexchat, &UserData) -> i32 + 'static,

Sets up a callback to be invoked every timeout milliseconds. The callback needs to be compatible with:

FnMut(&Hexchat, &UserData) -> i32

Arguments

• timeout - The timeout in milliseconds.
• callback - The FnOnce() callback.
• user_data - User data included with the callback and passed back to the callback during invocation.

Returns

• A Hook object that is can be used to deregister the callback.

pub fn hook_fd<F>( &self, fd: i32, flags: i32, callback: F, user_data: UserData ) -> Hookwhere F: FnMut(&Hexchat, i32, i32, &UserData) -> Eat + 'static,

Registers a callback to be called after the given timeout.

pub fn unhook(&self, hook: &mut Hook) -> UserData

Unhooks any Hook that was returned from a callback registration. Ownership of the user_data is transferred to the caller. Note: Hexchat unhooks all hooks automatically when a plugin is unloaded, so the client plugin doesn’t have to in that case.

Arguments

• hook - The callback hook to deregister with Hexchat.

Returns

• The user data that was registered with the callback using one of the hook commands. Ownership of this object is transferred to the caller.

pub fn emit_print( &self, event_name: &str, var_args: &[&str] ) -> Result<(), HexchatError>

Issues one of the Hexchat IRC events. The command works for any of the events listed in Settings > Text Events dialog.

Arguments

• event_name - The name of the Hexchat text event to send.
• var_args - A slice of &str’s containing the event’s arguments.

Returns

• On success, Ok(()) is returned; otherwise, Err(<HexchatError>).

pub fn emit_print_attrs( &self, event_attrs: &EventAttrs, event_name: &str, var_args: &[&str] ) -> Result<(), HexchatError>

Issues one of the Hexchat IRC events. The command works for any of the events listed in Settings > Text Events dialog.

Arguments

• event_attrs - A reference to an EventAttrs struct.
• event_name - The name of the Hexchat text event to send.
• var_args - A slice of &str’s containing the event’s arguments.

Returns

• On success, Ok(()) is returned; otherwise, Err(<HexchatError>).

pub fn nickcmp(&self, s1: &str, s2: &str) -> i32

Compares two nicknames, returning a similar value to strcmp(). If they’re equal (0), s1 < s2 (<0 - negative), or s1 > s2 (>0 positive).

Arguments

• s1 - The first nickname to compare.
• s2 - The second.

Returns

• If the first non-matching character is of lesser value for s1, a negative value is returned; if s1’s char is greater, then a non-0 postive value is returned. 0 is returned if they match.

pub fn strip(&self, text: &str, flags: StripFlags) -> Option<String>

Converts a string with text attributes and IRC colors embedded into a plain text string. Either IRC colors, or text attributes (or both) can be stripped out of the string.

Arguments

• text - The string to strip.
• flags - One of the StripFlags cases (StripMIrcColors, StripTextAttributes, StripBoth).

Returns

• Some(<stripped-string>) or None if the operation failed.

pub fn set_context(&self, context: &Context) -> Result<(), HexchatError>

Sets the currently active context to that bound to the Context object. The contexts are essentially the channels the user is in and has open tabs/windows to them. The Context object itself has a .set() method that can be invoked directly, which this command invokes.

Arguments

• context - The Context to make the currently active context.

Returns

• A result (Result<(), HexchatError>) where Ok(())indicates the context has been switched, and aHexchatError` if it didn’t.

pub fn find_context(&self, network: &str, channel: &str) -> Option<Context>

Returns a Context object bound to the requested server/channel. The object provides methods like print() that will execute the Hexchat print command in that tab/window related to the context. The Context::find() can also be invoked to find a context.

Arguments

• network - The network (e.g. “freenode”) of the context.
• channel - The channel name for the context (e.g. “##rust”).

Returns

• the context was found, i.e. if the user is joined to the channel specified currently, a Some(<Context>) is returned with the context object; None otherwise.

pub fn get_context(&self) -> Option<Context>

Returns a Context object for the current context (Hexchat tab/window currently visible in the app). This object can be used to invoke the Hexchat API within the context the object is bound to. Also, Context::get() will return a context object for the current context.

Returns

• The Context for the currently active context. This usually means the channel window the user has visible in the GUI.

pub fn get_info(&self, id: &str) -> Option<String>

Retrieves the info data with the given id. It returns None on failure and Some(String) on success. All information is returned as String data - even the “win_ptr”/“gtkwin_ptr” values, which can be parsed and cast to pointers.

Arguments

• id - The name/identifier for the information needed. A list of the names for some of these can be found on the Hexchat Plugin Interface page under hexchat_get_info(). These include “channel”, “network”, “topic”, etc.

Returns

• Some(<String>) is returned with the string value of the info requested. None is returned if there is no info with the requested id.

pub fn get_prefs(&self, name: &str) -> Option<PrefValue>

Returns the requested pref value, or None if it doesn’t exist. These are settings specific to Hexchat itself. It’s possible to get the user’s input box text cursor position via this command with “state_cursor”, for instance. Other preferences can be listed with the /set command.

Arguments

• name - The name of the pref to read.

Returns

• Some(PrefValue) if the pref exists, None otherwise.

pub fn list_get(&self, name: &str) -> Option<ListIterator>

Creates an iterator for the requested Hexchat list. This is modeled after how Hexchat implements the listing feature: rather than load all the list items up front, an internal list pointer is advanced to the current item, and the fields of which are accessible through the iterator’s .get_field() function. List iterators can also be created by invoking ListIterator::new(<list-name>). See the Hexchat Plugin Interface web page for more information on the related lists.

Arguments

• name - The name of the list to iterate over.

Returns

• If the list exists, Some(ListIterator) is returned; None otherwise.

pub fn pluginpref_set(&self, name: &str, value: PrefValue) -> bool

Writes a variable name and value to a configuration file maintained by Hexchat for your plugin. These can be accessed later using pluginpref_get(). A character representing the type of the pref is prepended to the value output to the config file. pluginpref_get() uses this when reading back values from the config file to return the correct variant of PrefValue.

Arguments

• name - The name of the pref to set.
• value - The value to set - an instance of one of the PrefValue types (StringVal, IntVal, or BoolVal).

Returns

• true if the operation succeeds, false otherwise.

pub fn pluginpref_get(&self, name: &str) -> Option<PrefValue>

Retrieves, from a config file that Hexchat manages for your plugin, the value for the named variable that had been previously created using pluginpref_set().

Arguments

• name - The name of the pref to load.

Returns

• Some(<PrefValue>) holding the value of the requested pref if it exists, None otherwise.

pub fn pluginpref_list(&self) -> Option<Vec<String>>

Returns a list of all the plugin pref variable names your plugin registered using pluginpref_set(). pluginpref_get() can be invoked with each item to get their values.

Returns

• Some(Vec<String>) if prefs exist for the plugin, None otherwise. The vector contains the names of the prefs registered.

pub fn plugingui_add( &self, filename: &str, name: &str, desc: &str, version: &str ) -> Plugin

Adds a dummy entry in Hexchat’s list of plugins. The “plugin” registered using this command is visible in the “Plugins and Scripts” dialog and using other slash “/” commands; however, that’s all it does. This command is useful when embedding a script interpreter that loads scripts as plugin code. Each script thus loaded can be visible to the user as a plugin. If writing a native plugin, you don’t need to be concerned with this command as your plugin’s info is registered during init from the PluginInfo object provided by your plugin_get_info() function.

Arguments

• filename - This can be the name of a script or binary.
• name - The name of the plugin.
• desc - The description of the plugin.
• version - A version string.

Returns

• A new Plugin object that represents the plugin entry in Hexchat. It can be used to deregister the plugin, and it (or a clone of it) needs to be retained; otherwise, the plugin entry will be removed when the last copy of the Plugin object goes out of scope.

pub fn plugingui_remove(&self, plugin: &Plugin)

Removes the dummy plugin entry from the Hexchat environment. The dummy plugin would have been registered using hexchat.plugingui_add().

Trait Implementations

impl Debug for Hexchat

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.