1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/signals.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,374 @@
1.4 +/**
1.5 + * @file signals.h Signal API
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + */
1.29 +#ifndef _PURPLE_SIGNALS_H_
1.30 +#define _PURPLE_SIGNALS_H_
1.31 +
1.32 +#include <glib.h>
1.33 +#include "value.h"
1.34 +
1.35 +#define PURPLE_CALLBACK(func) ((PurpleCallback)func)
1.36 +
1.37 +typedef void (*PurpleCallback)(void);
1.38 +typedef void (*PurpleSignalMarshalFunc)(PurpleCallback cb, va_list args,
1.39 + void *data, void **return_val);
1.40 +
1.41 +#ifdef __cplusplus
1.42 +extern "C" {
1.43 +#endif
1.44 +
1.45 +/**************************************************************************/
1.46 +/** @name Signal API */
1.47 +/**************************************************************************/
1.48 +/*@{*/
1.49 +
1.50 +/** The priority of a signal connected using purple_signal_connect().
1.51 + *
1.52 + * @see purple_signal_connect_priority()
1.53 + */
1.54 +#define PURPLE_SIGNAL_PRIORITY_DEFAULT 0
1.55 +/** The largest signal priority; signals with this priority will be called
1.56 + * <em>last</em>. (This is highest as in numerical value, not as in order of
1.57 + * importance.)
1.58 + *
1.59 + * @see purple_signal_connect_priority().
1.60 + */
1.61 +#define PURPLE_SIGNAL_PRIORITY_HIGHEST 9999
1.62 +/** The smallest signal priority; signals with this priority will be called
1.63 + * <em>first</em>. (This is lowest as in numerical value, not as in order of
1.64 + * importance.)
1.65 + *
1.66 + * @see purple_signal_connect_priority().
1.67 + */
1.68 +#define PURPLE_SIGNAL_PRIORITY_LOWEST -9999
1.69 +
1.70 +/**
1.71 + * Registers a signal in an instance.
1.72 + *
1.73 + * @param instance The instance to register the signal for.
1.74 + * @param signal The signal name.
1.75 + * @param marshal The marshal function.
1.76 + * @param ret_value The return value type, or NULL for no return value.
1.77 + * @param num_values The number of values to be passed to the callbacks.
1.78 + * @param ... The values to pass to the callbacks.
1.79 + *
1.80 + * @return The signal ID local to that instance, or 0 if the signal
1.81 + * couldn't be registered.
1.82 + *
1.83 + * @see PurpleValue
1.84 + */
1.85 +gulong purple_signal_register(void *instance, const char *signal,
1.86 + PurpleSignalMarshalFunc marshal,
1.87 + PurpleValue *ret_value, int num_values, ...);
1.88 +
1.89 +/**
1.90 + * Unregisters a signal in an instance.
1.91 + *
1.92 + * @param instance The instance to unregister the signal for.
1.93 + * @param signal The signal name.
1.94 + */
1.95 +void purple_signal_unregister(void *instance, const char *signal);
1.96 +
1.97 +/**
1.98 + * Unregisters all signals in an instance.
1.99 + *
1.100 + * @param instance The instance to unregister the signal for.
1.101 + */
1.102 +void purple_signals_unregister_by_instance(void *instance);
1.103 +
1.104 +/**
1.105 + * Returns a list of value types used for a signal.
1.106 + *
1.107 + * @param instance The instance the signal is registered to.
1.108 + * @param signal The signal.
1.109 + * @param ret_value The return value from the last signal handler.
1.110 + * @param num_values The returned number of values.
1.111 + * @param values The returned list of values.
1.112 + */
1.113 +void purple_signal_get_values(void *instance, const char *signal,
1.114 + PurpleValue **ret_value,
1.115 + int *num_values, PurpleValue ***values);
1.116 +
1.117 +/**
1.118 + * Connects a signal handler to a signal for a particular object.
1.119 + *
1.120 + * Take care not to register a handler function twice. Purple will
1.121 + * not correct any mistakes for you in this area.
1.122 + *
1.123 + * @param instance The instance to connect to.
1.124 + * @param signal The name of the signal to connect.
1.125 + * @param handle The handle of the receiver.
1.126 + * @param func The callback function.
1.127 + * @param data The data to pass to the callback function.
1.128 + * @param priority The priority with which the handler should be called. Signal
1.129 + * handlers are called in ascending numerical order of @a
1.130 + * priority from #PURPLE_SIGNAL_PRIORITY_LOWEST to
1.131 + * #PURPLE_SIGNAL_PRIORITY_HIGHEST.
1.132 + *
1.133 + * @return The signal handler ID.
1.134 + *
1.135 + * @see purple_signal_disconnect()
1.136 + */
1.137 +gulong purple_signal_connect_priority(void *instance, const char *signal,
1.138 + void *handle, PurpleCallback func, void *data, int priority);
1.139 +
1.140 +/**
1.141 + * Connects a signal handler to a signal for a particular object.
1.142 + * (Its priority defaults to 0, aka #PURPLE_SIGNAL_PRIORITY_DEFAULT.)
1.143 + *
1.144 + * Take care not to register a handler function twice. Purple will
1.145 + * not correct any mistakes for you in this area.
1.146 + *
1.147 + * @param instance The instance to connect to.
1.148 + * @param signal The name of the signal to connect.
1.149 + * @param handle The handle of the receiver.
1.150 + * @param func The callback function.
1.151 + * @param data The data to pass to the callback function.
1.152 + *
1.153 + * @return The signal handler ID.
1.154 + *
1.155 + * @see purple_signal_disconnect()
1.156 + */
1.157 +gulong purple_signal_connect(void *instance, const char *signal,
1.158 + void *handle, PurpleCallback func, void *data);
1.159 +
1.160 +/**
1.161 + * Connects a signal handler to a signal for a particular object.
1.162 + *
1.163 + * The signal handler will take a va_args of arguments, instead of
1.164 + * individual arguments.
1.165 + *
1.166 + * Take care not to register a handler function twice. Purple will
1.167 + * not correct any mistakes for you in this area.
1.168 + *
1.169 + * @param instance The instance to connect to.
1.170 + * @param signal The name of the signal to connect.
1.171 + * @param handle The handle of the receiver.
1.172 + * @param func The callback function.
1.173 + * @param data The data to pass to the callback function.
1.174 + * @param priority The priority with which the handler should be called. Signal
1.175 + * handlers are called in ascending numerical order of @a
1.176 + * priority from #PURPLE_SIGNAL_PRIORITY_LOWEST to
1.177 + * #PURPLE_SIGNAL_PRIORITY_HIGHEST.
1.178 + *
1.179 + * @return The signal handler ID.
1.180 + *
1.181 + * @see purple_signal_disconnect()
1.182 + */
1.183 +gulong purple_signal_connect_priority_vargs(void *instance, const char *signal,
1.184 + void *handle, PurpleCallback func, void *data, int priority);
1.185 +
1.186 +/**
1.187 + * Connects a signal handler to a signal for a particular object.
1.188 + * (Its priority defaults to 0, aka #PURPLE_SIGNAL_PRIORITY_DEFAULT.)
1.189 + *
1.190 + * The signal handler will take a va_args of arguments, instead of
1.191 + * individual arguments.
1.192 + *
1.193 + * Take care not to register a handler function twice. Purple will
1.194 + * not correct any mistakes for you in this area.
1.195 + *
1.196 + * @param instance The instance to connect to.
1.197 + * @param signal The name of the signal to connect.
1.198 + * @param handle The handle of the receiver.
1.199 + * @param func The callback function.
1.200 + * @param data The data to pass to the callback function.
1.201 + *
1.202 + * @return The signal handler ID.
1.203 + *
1.204 + * @see purple_signal_disconnect()
1.205 + */
1.206 +gulong purple_signal_connect_vargs(void *instance, const char *signal,
1.207 + void *handle, PurpleCallback func, void *data);
1.208 +
1.209 +/**
1.210 + * Disconnects a signal handler from a signal on an object.
1.211 + *
1.212 + * @param instance The instance to disconnect from.
1.213 + * @param signal The name of the signal to disconnect.
1.214 + * @param handle The handle of the receiver.
1.215 + * @param func The registered function to disconnect.
1.216 + *
1.217 + * @see purple_signal_connect()
1.218 + */
1.219 +void purple_signal_disconnect(void *instance, const char *signal,
1.220 + void *handle, PurpleCallback func);
1.221 +
1.222 +/**
1.223 + * Removes all callbacks associated with a receiver handle.
1.224 + *
1.225 + * @param handle The receiver handle.
1.226 + */
1.227 +void purple_signals_disconnect_by_handle(void *handle);
1.228 +
1.229 +/**
1.230 + * Emits a signal.
1.231 + *
1.232 + * @param instance The instance emitting the signal.
1.233 + * @param signal The signal being emitted.
1.234 + *
1.235 + * @see purple_signal_connect()
1.236 + * @see purple_signal_disconnect()
1.237 + */
1.238 +void purple_signal_emit(void *instance, const char *signal, ...);
1.239 +
1.240 +/**
1.241 + * Emits a signal, using a va_list of arguments.
1.242 + *
1.243 + * @param instance The instance emitting the signal.
1.244 + * @param signal The signal being emitted.
1.245 + * @param args The arguments list.
1.246 + *
1.247 + * @see purple_signal_connect()
1.248 + * @see purple_signal_disconnect()
1.249 + */
1.250 +void purple_signal_emit_vargs(void *instance, const char *signal, va_list args);
1.251 +
1.252 +/**
1.253 + * Emits a signal and returns the first non-NULL return value.
1.254 + *
1.255 + * Further signal handlers are NOT called after a handler returns
1.256 + * something other than NULL.
1.257 + *
1.258 + * @param instance The instance emitting the signal.
1.259 + * @param signal The signal being emitted.
1.260 + *
1.261 + * @return The first non-NULL return value
1.262 + */
1.263 +void *purple_signal_emit_return_1(void *instance, const char *signal, ...);
1.264 +
1.265 +/**
1.266 + * Emits a signal and returns the first non-NULL return value.
1.267 + *
1.268 + * Further signal handlers are NOT called after a handler returns
1.269 + * something other than NULL.
1.270 + *
1.271 + * @param instance The instance emitting the signal.
1.272 + * @param signal The signal being emitted.
1.273 + * @param args The arguments list.
1.274 + *
1.275 + * @return The first non-NULL return value
1.276 + */
1.277 +void *purple_signal_emit_vargs_return_1(void *instance, const char *signal,
1.278 + va_list args);
1.279 +
1.280 +/**
1.281 + * Initializes the signals subsystem.
1.282 + */
1.283 +void purple_signals_init(void);
1.284 +
1.285 +/**
1.286 + * Uninitializes the signals subsystem.
1.287 + */
1.288 +void purple_signals_uninit(void);
1.289 +
1.290 +/*@}*/
1.291 +
1.292 +/**************************************************************************/
1.293 +/** @name Marshal Functions */
1.294 +/**************************************************************************/
1.295 +/*@{*/
1.296 +
1.297 +void purple_marshal_VOID(
1.298 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.299 +void purple_marshal_VOID__INT(
1.300 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.301 +void purple_marshal_VOID__INT_INT(
1.302 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.303 +void purple_marshal_VOID__POINTER(
1.304 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.305 +void purple_marshal_VOID__POINTER_UINT(
1.306 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.307 +void purple_marshal_VOID__POINTER_INT_INT(
1.308 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.309 +void purple_marshal_VOID__POINTER_INT_POINTER(
1.310 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.311 +void purple_marshal_VOID__POINTER_POINTER(
1.312 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.313 +void purple_marshal_VOID__POINTER_POINTER_UINT(
1.314 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.315 +void purple_marshal_VOID__POINTER_POINTER_UINT_UINT(
1.316 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.317 +void purple_marshal_VOID__POINTER_POINTER_POINTER(
1.318 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.319 +void purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER(
1.320 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.321 +void purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER_POINTER(
1.322 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.323 +void purple_marshal_VOID__POINTER_POINTER_POINTER_UINT(
1.324 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.325 +void purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER_UINT(
1.326 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.327 +void purple_marshal_VOID__POINTER_POINTER_POINTER_UINT_UINT(
1.328 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.329 +
1.330 +void purple_marshal_INT__INT(
1.331 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.332 +void purple_marshal_INT__INT_INT(
1.333 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.334 +void purple_marshal_INT__POINTER_POINTER(
1.335 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.336 +void purple_marshal_INT__POINTER_POINTER_POINTER_POINTER_POINTER(
1.337 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.338 +
1.339 +void purple_marshal_BOOLEAN__POINTER(
1.340 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.341 +void purple_marshal_BOOLEAN__POINTER_POINTER(
1.342 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.343 +void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER(
1.344 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.345 +void purple_marshal_BOOLEAN__POINTER_POINTER_UINT(
1.346 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.347 +void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_UINT(
1.348 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.349 +void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER(
1.350 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.351 +void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER(
1.352 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.353 +void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_UINT(
1.354 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.355 +void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER_POINTER(
1.356 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.357 +
1.358 +void purple_marshal_BOOLEAN__INT_POINTER(
1.359 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.360 +
1.361 +void purple_marshal_POINTER__POINTER_INT(
1.362 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.363 +void purple_marshal_POINTER__POINTER_INT64(
1.364 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.365 +void purple_marshal_POINTER__POINTER_INT_BOOLEAN(
1.366 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.367 +void purple_marshal_POINTER__POINTER_INT64_BOOLEAN(
1.368 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.369 +void purple_marshal_POINTER__POINTER_POINTER(
1.370 + PurpleCallback cb, va_list args, void *data, void **return_val);
1.371 +/*@}*/
1.372 +
1.373 +#ifdef __cplusplus
1.374 +}
1.375 +#endif
1.376 +
1.377 +#endif /* _PURPLE_SIGNALS_H_ */