1/* GIO - GLib Input, Output and Streaming Library
2 *
3 * Copyright (C) 2006-2007 Red Hat, Inc.
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
17 *
18 * Author: Alexander Larsson <alexl@redhat.com>
19 */
20
21#ifndef __G_IO_MODULE_H__
22#define __G_IO_MODULE_H__
23
24#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
25#error "Only <gio/gio.h> can be included directly."
26#endif
27
28#include <gio/giotypes.h>
29#include <gmodule.h>
30
31G_BEGIN_DECLS
32
33typedef struct _GIOModuleScope GIOModuleScope;
34
35GLIB_AVAILABLE_IN_2_30
36GIOModuleScope * g_io_module_scope_new (GIOModuleScopeFlags flags);
37GLIB_AVAILABLE_IN_2_30
38void g_io_module_scope_free (GIOModuleScope *scope);
39GLIB_AVAILABLE_IN_2_30
40void g_io_module_scope_block (GIOModuleScope *scope,
41 const gchar *basename);
42
43#define G_IO_TYPE_MODULE (g_io_module_get_type ())
44#define G_IO_MODULE(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), G_IO_TYPE_MODULE, GIOModule))
45#define G_IO_MODULE_CLASS(k) (G_TYPE_CHECK_CLASS_CAST((k), G_IO_TYPE_MODULE, GIOModuleClass))
46#define G_IO_IS_MODULE(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_IO_TYPE_MODULE))
47#define G_IO_IS_MODULE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_IO_TYPE_MODULE))
48#define G_IO_MODULE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_IO_TYPE_MODULE, GIOModuleClass))
49
50/**
51 * GIOModule:
52 *
53 * Opaque module base class for extending GIO.
54 **/
55typedef struct _GIOModuleClass GIOModuleClass;
56
57GLIB_AVAILABLE_IN_ALL
58GType g_io_module_get_type (void) G_GNUC_CONST;
59GLIB_AVAILABLE_IN_ALL
60GIOModule *g_io_module_new (const gchar *filename);
61
62GLIB_AVAILABLE_IN_ALL
63void g_io_modules_scan_all_in_directory (const char *dirname);
64GLIB_AVAILABLE_IN_ALL
65GList *g_io_modules_load_all_in_directory (const gchar *dirname);
66
67GLIB_AVAILABLE_IN_2_30
68void g_io_modules_scan_all_in_directory_with_scope (const gchar *dirname,
69 GIOModuleScope *scope);
70GLIB_AVAILABLE_IN_2_30
71GList *g_io_modules_load_all_in_directory_with_scope (const gchar *dirname,
72 GIOModuleScope *scope);
73
74GLIB_AVAILABLE_IN_ALL
75GIOExtensionPoint *g_io_extension_point_register (const char *name);
76GLIB_AVAILABLE_IN_ALL
77GIOExtensionPoint *g_io_extension_point_lookup (const char *name);
78GLIB_AVAILABLE_IN_ALL
79void g_io_extension_point_set_required_type (GIOExtensionPoint *extension_point,
80 GType type);
81GLIB_AVAILABLE_IN_ALL
82GType g_io_extension_point_get_required_type (GIOExtensionPoint *extension_point);
83GLIB_AVAILABLE_IN_ALL
84GList *g_io_extension_point_get_extensions (GIOExtensionPoint *extension_point);
85GLIB_AVAILABLE_IN_ALL
86GIOExtension * g_io_extension_point_get_extension_by_name (GIOExtensionPoint *extension_point,
87 const char *name);
88GLIB_AVAILABLE_IN_ALL
89GIOExtension * g_io_extension_point_implement (const char *extension_point_name,
90 GType type,
91 const char *extension_name,
92 gint priority);
93
94GLIB_AVAILABLE_IN_ALL
95GType g_io_extension_get_type (GIOExtension *extension);
96GLIB_AVAILABLE_IN_ALL
97const char * g_io_extension_get_name (GIOExtension *extension);
98GLIB_AVAILABLE_IN_ALL
99gint g_io_extension_get_priority (GIOExtension *extension);
100GLIB_AVAILABLE_IN_ALL
101GTypeClass* g_io_extension_ref_class (GIOExtension *extension);
102
103
104/* API for the modules to implement */
105
106/**
107 * g_io_module_load:
108 * @module: a #GIOModule.
109 *
110 * Required API for GIO modules to implement.
111 *
112 * This function is run after the module has been loaded into GIO,
113 * to initialize the module. Typically, this function will call
114 * g_io_extension_point_implement().
115 *
116 * Since 2.56, this function should be named `g_io_<modulename>_load`, where
117 * `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
118 * everything after the first dot removed, and with `-` replaced with `_`
119 * throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
120 * Using the new symbol names avoids name clashes when building modules
121 * statically. The old symbol names continue to be supported, but cannot be used
122 * for static builds.
123 **/
124GLIB_AVAILABLE_IN_ALL
125void g_io_module_load (GIOModule *module);
126
127/**
128 * g_io_module_unload:
129 * @module: a #GIOModule.
130 *
131 * Required API for GIO modules to implement.
132 *
133 * This function is run when the module is being unloaded from GIO,
134 * to finalize the module.
135 *
136 * Since 2.56, this function should be named `g_io_<modulename>_unload`, where
137 * `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
138 * everything after the first dot removed, and with `-` replaced with `_`
139 * throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
140 * Using the new symbol names avoids name clashes when building modules
141 * statically. The old symbol names continue to be supported, but cannot be used
142 * for static builds.
143 **/
144GLIB_AVAILABLE_IN_ALL
145void g_io_module_unload (GIOModule *module);
146
147/**
148 * g_io_module_query:
149 *
150 * Optional API for GIO modules to implement.
151 *
152 * Should return a list of all the extension points that may be
153 * implemented in this module.
154 *
155 * This method will not be called in normal use, however it may be
156 * called when probing existing modules and recording which extension
157 * points that this model is used for. This means we won't have to
158 * load and initialize this module unless its needed.
159 *
160 * If this function is not implemented by the module the module will
161 * always be loaded, initialized and then unloaded on application
162 * startup so that it can register its extension points during init.
163 *
164 * Note that a module need not actually implement all the extension
165 * points that g_io_module_query() returns, since the exact list of
166 * extension may depend on runtime issues. However all extension
167 * points actually implemented must be returned by g_io_module_query()
168 * (if defined).
169 *
170 * When installing a module that implements g_io_module_query() you must
171 * run gio-querymodules in order to build the cache files required for
172 * lazy loading.
173 *
174 * Since 2.56, this function should be named `g_io_<modulename>_query`, where
175 * `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
176 * everything after the first dot removed, and with `-` replaced with `_`
177 * throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
178 * Using the new symbol names avoids name clashes when building modules
179 * statically. The old symbol names continue to be supported, but cannot be used
180 * for static builds.
181 *
182 * Returns: (transfer full): A %NULL-terminated array of strings,
183 * listing the supported extension points of the module. The array
184 * must be suitable for freeing with g_strfreev().
185 *
186 * Since: 2.24
187 **/
188GLIB_AVAILABLE_IN_ALL
189char **g_io_module_query (void);
190
191G_END_DECLS
192
193#endif /* __G_IO_MODULE_H__ */
194