glib2.0_2.20.1
[mer:glib2_0.git] / docs / reference / glib / xml / windows.xml
1 <refentry id="glib-Windows-Compatibility-Functions">
2 <refmeta>
3 <refentrytitle role="top_of_page" id="glib-Windows-Compatibility-Functions.top_of_page">Windows Compatibility Functions</refentrytitle>
4 <manvolnum>3</manvolnum>
5 <refmiscinfo>GLIB Library</refmiscinfo>
6 </refmeta>
7
8 <refnamediv>
9 <refname>Windows Compatibility Functions</refname>
10 <refpurpose>UNIX emulation on Windows</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv id="glib-Windows-Compatibility-Functions.synopsis" role="synopsis">
14 <title role="synopsis.title">Synopsis</title>
15
16 <synopsis>
17
18 #include &lt;glib.h&gt;
19
20 #define             <link linkend="MAXPATHLEN--CAPS">MAXPATHLEN</link>
21 <link linkend="gchar">gchar</link>*              <link linkend="g-win32-error-message">g_win32_error_message</link>               (<link linkend="gint">gint</link> error);
22 <link linkend="gchar">gchar</link>*              <link linkend="g-win32-getlocale">g_win32_getlocale</link>                   (void);
23 <link linkend="gchar">gchar</link>*              <link linkend="g-win32-get-package-installation-directory">g_win32_get_package_installation_directory</link>
24                                                         (const <link linkend="gchar">gchar</link> *package,
25                                                          const <link linkend="gchar">gchar</link> *dll_name);
26 <link linkend="gchar">gchar</link>*              <link linkend="g-win32-get-package-installation-directory-of-module">g_win32_get_package_installation_directory_of_module</link>
27                                                         (<link linkend="gpointer">gpointer</link> hmodule);
28 <link linkend="gchar">gchar</link>*              <link linkend="g-win32-get-package-installation-subdirectory">g_win32_get_package_installation_subdirectory</link>
29                                                         (const <link linkend="gchar">gchar</link> *package,
30                                                          const <link linkend="gchar">gchar</link> *dll_name,
31                                                          const <link linkend="gchar">gchar</link> *subdir);
32 <link linkend="guint">guint</link>               <link linkend="g-win32-get-windows-version">g_win32_get_windows_version</link>         (void);
33 <link linkend="gchar">gchar</link>*              <link linkend="g-win32-locale-filename-from-utf8">g_win32_locale_filename_from_utf8</link>   (const <link linkend="gchar">gchar</link> *utf8filename);
34 #define             <link linkend="G-WIN32-DLLMAIN-FOR-DLL-NAME--CAPS">G_WIN32_DLLMAIN_FOR_DLL_NAME</link>        (static, dll_name)
35 #define             <link linkend="G-WIN32-HAVE-WIDECHAR-API--CAPS">G_WIN32_HAVE_WIDECHAR_API</link>           ()
36 #define             <link linkend="G-WIN32-IS-NT-BASED--CAPS">G_WIN32_IS_NT_BASED</link>                 ()
37 </synopsis>
38 </refsynopsisdiv>
39
40
41
42
43
44
45
46
47
48 <refsect1 id="glib-Windows-Compatibility-Functions.description" role="desc">
49 <title role="desc.title">Description</title>
50 <para>
51 These functions provide some level of UNIX emulation on the Windows platform.
52 If your application really needs the POSIX APIs, we suggest you try the Cygwin
53 project.
54 </para>
55 </refsect1>
56
57 <refsect1 id="glib-Windows-Compatibility-Functions.details" role="details">
58 <title role="details.title">Details</title>
59 <refsect2 id="MAXPATHLEN--CAPS" role="macro">
60 <title>MAXPATHLEN</title>
61 <indexterm zone="MAXPATHLEN--CAPS"><primary>MAXPATHLEN</primary></indexterm><programlisting>#define MAXPATHLEN 1024
62 </programlisting>
63 <para>
64 Provided for UNIX emulation on Windows; equivalent to UNIX
65 macro <link linkend="MAXPATHLEN--CAPS"><literal>MAXPATHLEN</literal></link>, which is the maximum length of a filename
66 (including full path).
67 </para></refsect2>
68 <refsect2 id="g-win32-error-message" role="function">
69 <title>g_win32_error_message ()</title>
70 <indexterm zone="g-win32-error-message"><primary sortas="win32_error_message">g_win32_error_message</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_win32_error_message               (<link linkend="gint">gint</link> error);</programlisting>
71 <para>
72 Translate a Win32 error code (as returned by <link linkend="GetLastError"><function>GetLastError()</function></link>) into
73 the corresponding message. The message is either language neutral,
74 or in the thread's language, or the user's language, the system's
75 language, or US English (see docs for <link linkend="FormatMessage"><function>FormatMessage()</function></link>). The
76 returned string is in UTF-8. It should be deallocated with
77 <link linkend="g-free"><function>g_free()</function></link>.</para>
78 <para>
79 </para><variablelist role="params">
80 <varlistentry><term><parameter>error</parameter>&#160;:</term>
81 <listitem><simpara> error code.
82 </simpara></listitem></varlistentry>
83 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> newly-allocated error message
84 </simpara></listitem></varlistentry>
85 </variablelist></refsect2>
86 <refsect2 id="g-win32-getlocale" role="function">
87 <title>g_win32_getlocale ()</title>
88 <indexterm zone="g-win32-getlocale"><primary sortas="win32_getlocale">g_win32_getlocale</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_win32_getlocale                   (void);</programlisting>
89 <para>
90 The <link linkend="setlocale"><function>setlocale()</function></link> function in the Microsoft C library uses locale
91 names of the form "English_United States.1252" etc. We want the
92 UNIXish standard form "en_US", "zh_TW" etc. This function gets the
93 current thread locale from Windows - without any encoding info -
94 and returns it as a string of the above form for use in forming
95 file names etc. The returned string should be deallocated with
96 <link linkend="g-free"><function>g_free()</function></link>.</para>
97 <para>
98 </para><variablelist role="params">
99 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> newly-allocated locale name.
100 </simpara></listitem></varlistentry>
101 </variablelist></refsect2>
102 <refsect2 id="g-win32-get-package-installation-directory" role="function" condition="deprecated:">
103 <title>g_win32_get_package_installation_directory ()</title>
104 <indexterm zone="g-win32-get-package-installation-directory" role="deprecated"><primary sortas="win32_get_package_installation_directory">g_win32_get_package_installation_directory</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_win32_get_package_installation_directory
105                                                         (const <link linkend="gchar">gchar</link> *package,
106                                                          const <link linkend="gchar">gchar</link> *dll_name);</programlisting>
107 <warning><para><literal>g_win32_get_package_installation_directory</literal> is deprecated and should not be used in newly-written code.</para></warning>
108 <para>
109 Try to determine the installation directory for a software package.
110 </para>
111 <para>
112 This function is deprecated. Use
113 <link linkend="g-win32-get-package-installation-directory-of-module"><function>g_win32_get_package_installation_directory_of_module()</function></link> instead.
114 </para>
115 <para>
116 The use of <parameter>package</parameter> is deprecated. You should always pass <link linkend="NULL--CAPS"><literal>NULL</literal></link>. A
117 warning is printed if non-NULL is passed as <parameter>package</parameter>.
118 </para>
119 <para>
120 The original intended use of <parameter>package</parameter> was for a short identifier of
121 the package, typically the same identifier as used for
122 <literal>GETTEXT_PACKAGE</literal> in software configured using GNU
123 autotools. The function first looks in the Windows Registry for the
124 value <literal>&num;InstallationDirectory</literal> in the key
125 <literal>&num;HKLM\Software@package</literal>, and if that value
126 exists and is a string, returns that.
127 </para>
128 <para>
129 It is strongly recommended that packagers of GLib-using libraries
130 for Windows do not store installation paths in the Registry to be
131 used by this function as that interfers with having several
132 parallel installations of the library. Enabling multiple
133 installations of different versions of some GLib-using library, or
134 GLib itself, is desirable for various reasons.
135 </para>
136 <para>
137 For this reason it is recommeded to always pass <link linkend="NULL--CAPS"><literal>NULL</literal></link> as
138 <parameter>package</parameter> to this function, to avoid the temptation to use the
139 Registry. In version 2.20 of GLib the <parameter>package</parameter> parameter
140 will be ignored and this function won't look in the Registry at all.
141 </para>
142 <para>
143 If <parameter>package</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, or the above value isn't found in the
144 Registry, but <parameter>dll_name</parameter> is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it should name a DLL loaded
145 into the current process. Typically that would be the name of the
146 DLL calling this function, looking for its installation
147 directory. The function then asks Windows what directory that DLL
148 was loaded from. If that directory's last component is "bin" or
149 "lib", the parent directory is returned, otherwise the directory
150 itself. If that DLL isn't loaded, the function proceeds as if
151 <parameter>dll_name</parameter> was <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
152 </para>
153 <para>
154 If both <parameter>package</parameter> and <parameter>dll_name</parameter> are <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the directory from where
155 the main executable of the process was loaded is used instead in
156 the same way as above.</para>
157 <para>
158 </para><variablelist role="params">
159 <varlistentry><term><parameter>package</parameter>&#160;:</term>
160 <listitem><simpara> You should pass <link linkend="NULL--CAPS"><literal>NULL</literal></link> for this.
161 </simpara></listitem></varlistentry>
162 <varlistentry><term><parameter>dll_name</parameter>&#160;:</term>
163 <listitem><simpara> The name of a DLL that a package provides in UTF-8, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
164 </simpara></listitem></varlistentry>
165 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a string containing the installation directory for
166 <parameter>package</parameter>. The string is in the GLib file name encoding,
167 i.e. UTF-8. The return value should be freed with <link linkend="g-free"><function>g_free()</function></link> when not
168 needed any longer. If the function fails <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.
169
170 <parameter>Deprecated</parameter>:2.18: Pass the HMODULE of a DLL or EXE to
171 <link linkend="g-win32-get-package-installation-directory-of-module"><function>g_win32_get_package_installation_directory_of_module()</function></link> instead.
172 </simpara></listitem></varlistentry>
173 </variablelist></refsect2>
174 <refsect2 id="g-win32-get-package-installation-directory-of-module" role="function" condition="since:2.16">
175 <title>g_win32_get_package_installation_directory_of_module ()</title>
176 <indexterm zone="g-win32-get-package-installation-directory-of-module" role="2.16"><primary sortas="win32_get_package_installation_directory_of_module">g_win32_get_package_installation_directory_of_module</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_win32_get_package_installation_directory_of_module
177                                                         (<link linkend="gpointer">gpointer</link> hmodule);</programlisting>
178 <para>
179 This function tries to determine the installation directory of a
180 software package based on the location of a DLL of the software
181 package.
182 </para>
183 <para>
184 <parameter>hmodule</parameter> should be the handle of a loaded DLL or <link linkend="NULL--CAPS"><literal>NULL</literal></link>. The
185 function looks up the directory that DLL was loaded from. If
186 <parameter>hmodule</parameter> is NULL, the directory the main executable of the current
187 process is looked up. If that directory's last component is "bin"
188 or "lib", its parent directory is returned, otherwise the directory
189 itself.
190 </para>
191 <para>
192 It thus makes sense to pass only the handle to a "public" DLL of a
193 software package to this function, as such DLLs typically are known
194 to be installed in a "bin" or occasionally "lib" subfolder of the
195 installation folder. DLLs that are of the dynamically loaded module
196 or plugin variety are often located in more private locations
197 deeper down in the tree, from which it is impossible for GLib to
198 deduce the root of the package installation.
199 </para>
200 <para>
201 The typical use case for this function is to have a <link linkend="DllMain"><function>DllMain()</function></link> that
202 saves the handle for the DLL. Then when code in the DLL needs to
203 construct names of files in the installation tree it calls this
204 function passing the DLL handle.</para>
205 <para>
206 </para><variablelist role="params">
207 <varlistentry><term><parameter>hmodule</parameter>&#160;:</term>
208 <listitem><simpara> The Win32 handle for a DLL loaded into the current process, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
209 </simpara></listitem></varlistentry>
210 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a string containing the guessed installation directory for
211 the software package <parameter>hmodule</parameter> is from. The string is in the GLib
212 file name encoding, i.e. UTF-8. The return value should be freed
213 with <link linkend="g-free"><function>g_free()</function></link> when not needed any longer. If the function fails
214 <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.
215
216 </simpara></listitem></varlistentry>
217 </variablelist><para role="since">Since 2.16</para></refsect2>
218 <refsect2 id="g-win32-get-package-installation-subdirectory" role="function" condition="deprecated:">
219 <title>g_win32_get_package_installation_subdirectory ()</title>
220 <indexterm zone="g-win32-get-package-installation-subdirectory" role="deprecated"><primary sortas="win32_get_package_installation_subdirectory">g_win32_get_package_installation_subdirectory</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_win32_get_package_installation_subdirectory
221                                                         (const <link linkend="gchar">gchar</link> *package,
222                                                          const <link linkend="gchar">gchar</link> *dll_name,
223                                                          const <link linkend="gchar">gchar</link> *subdir);</programlisting>
224 <warning><para><literal>g_win32_get_package_installation_subdirectory</literal> is deprecated and should not be used in newly-written code.</para></warning>
225 <para>
226 This function is deprecated. Use
227 <link linkend="g-win32-get-package-installation-directory-of-module"><function>g_win32_get_package_installation_directory_of_module()</function></link> and
228 <link linkend="g-build-filename"><function>g_build_filename()</function></link> instead.
229 </para>
230 <para>
231 Returns a newly-allocated string containing the path of the
232 subdirectory <parameter>subdir</parameter> in the return value from calling
233 <link linkend="g-win32-get-package-installation-directory"><function>g_win32_get_package_installation_directory()</function></link> with the <parameter>package</parameter> and
234 <parameter>dll_name</parameter> parameters. See the documentation for
235 <link linkend="g-win32-get-package-installation-directory"><function>g_win32_get_package_installation_directory()</function></link> for more details. In
236 particular, note that it is deprecated to pass anything except NULL
237 as <parameter>package</parameter>.</para>
238 <para>
239 </para><variablelist role="params">
240 <varlistentry><term><parameter>package</parameter>&#160;:</term>
241 <listitem><simpara> You should pass <link linkend="NULL--CAPS"><literal>NULL</literal></link> for this.
242 </simpara></listitem></varlistentry>
243 <varlistentry><term><parameter>dll_name</parameter>&#160;:</term>
244 <listitem><simpara> The name of a DLL that a package provides, in UTF-8, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
245 </simpara></listitem></varlistentry>
246 <varlistentry><term><parameter>subdir</parameter>&#160;:</term>
247 <listitem><simpara> A subdirectory of the package installation directory, also in UTF-8
248 </simpara></listitem></varlistentry>
249 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a string containing the complete path to <parameter>subdir</parameter> inside
250 the installation directory of <parameter>package</parameter>. The returned string is in
251 the GLib file name encoding, i.e. UTF-8. The return value should be
252 freed with <link linkend="g-free"><function>g_free()</function></link> when no longer needed. If something goes wrong,
253 <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.
254
255 <parameter>Deprecated</parameter>:2.18: Pass the HMODULE of a DLL or EXE to
256 <link linkend="g-win32-get-package-installation-directory-of-module"><function>g_win32_get_package_installation_directory_of_module()</function></link> instead, and
257 then construct a subdirectory pathname with <link linkend="g-build-filename"><function>g_build_filename()</function></link>.
258 </simpara></listitem></varlistentry>
259 </variablelist></refsect2>
260 <refsect2 id="g-win32-get-windows-version" role="function" condition="since:2.6">
261 <title>g_win32_get_windows_version ()</title>
262 <indexterm zone="g-win32-get-windows-version" role="2.6"><primary sortas="win32_get_windows_version">g_win32_get_windows_version</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_win32_get_windows_version         (void);</programlisting>
263 <para>
264 Returns version information for the Windows operating system the
265 code is running on. See MSDN documentation for the <link linkend="GetVersion"><function>GetVersion()</function></link>
266 function. To summarize, the most significant bit is one on Win9x,
267 and zero on NT-based systems. Since version 2.14, GLib works only
268 on NT-based systems, so checking whether your are running on Win9x
269 in your own software is moot. The least significant byte is 4 on
270 Windows NT 4, and 5 on Windows XP. Software that needs really
271 detailled version and feature information should use Win32 API like
272 <link linkend="GetVersionEx"><function>GetVersionEx()</function></link> and <link linkend="VerifyVersionInfo"><function>VerifyVersionInfo()</function></link>.</para>
273 <para>
274 </para><variablelist role="params">
275 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The version information.
276
277 </simpara></listitem></varlistentry>
278 </variablelist><para role="since">Since 2.6</para></refsect2>
279 <refsect2 id="g-win32-locale-filename-from-utf8" role="function" condition="since:2.8">
280 <title>g_win32_locale_filename_from_utf8 ()</title>
281 <indexterm zone="g-win32-locale-filename-from-utf8" role="2.8"><primary sortas="win32_locale_filename_from_utf8">g_win32_locale_filename_from_utf8</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_win32_locale_filename_from_utf8   (const <link linkend="gchar">gchar</link> *utf8filename);</programlisting>
282 <para>
283 Converts a filename from UTF-8 to the system codepage.
284 </para>
285 <para>
286 On NT-based Windows, on NTFS file systems, file names are in
287 Unicode. It is quite possible that Unicode file names contain
288 characters not representable in the system codepage. (For instance,
289 Greek or Cyrillic characters on Western European or US Windows
290 installations, or various less common CJK characters on CJK Windows
291 installations.)
292 </para>
293 <para>
294 In such a case, and if the filename refers to an existing file, and
295 the file system stores alternate short (8.3) names for directory
296 entries, the short form of the filename is returned. Note that the
297 "short" name might in fact be longer than the Unicode name if the
298 Unicode name has very short pathname components containing
299 non-ASCII characters. If no system codepage name for the file is
300 possible, <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.
301 </para>
302 <para>
303 The return value is dynamically allocated and should be freed with
304 <link linkend="g-free"><function>g_free()</function></link> when no longer needed.</para>
305 <para>
306 </para><variablelist role="params">
307 <varlistentry><term><parameter>utf8filename</parameter>&#160;:</term>
308 <listitem><simpara> a UTF-8 encoded filename.
309 </simpara></listitem></varlistentry>
310 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The converted filename, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> on conversion
311 failure and lack of short names.
312
313 </simpara></listitem></varlistentry>
314 </variablelist><para role="since">Since 2.8</para></refsect2>
315 <refsect2 id="G-WIN32-DLLMAIN-FOR-DLL-NAME--CAPS" role="macro" condition="deprecated:">
316 <title>G_WIN32_DLLMAIN_FOR_DLL_NAME()</title>
317 <indexterm zone="G-WIN32-DLLMAIN-FOR-DLL-NAME--CAPS" role="deprecated"><primary sortas="WIN32_DLLMAIN_FOR_DLL_NAME">G_WIN32_DLLMAIN_FOR_DLL_NAME</primary></indexterm><programlisting>#define             G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)</programlisting>
318 <warning><para><literal>G_WIN32_DLLMAIN_FOR_DLL_NAME</literal> is deprecated and should not be used in newly-written code.</para></warning>
319 <para>
320 On Windows, this macro defines a <link linkend="DllMain"><function>DllMain()</function></link> function that stores the actual
321 DLL name that the code being compiled will be included in.
322 </para>
323 <para>
324 On non-Windows platforms, expands to nothing.
325 </para><variablelist role="params">
326 <varlistentry><term><parameter>static</parameter>&#160;:</term>
327 <listitem><simpara>empty or "static".
328 </simpara></listitem></varlistentry>
329 <varlistentry><term><parameter>dll_name</parameter>&#160;:</term>
330 <listitem><simpara>the name of the (pointer to the) char array where the DLL name 
331    will be stored. If this is used, you must also include
332    <filename>windows.h</filename>. If you need a more complex DLL entry
333    point function, you cannot use this.
334 </simpara></listitem></varlistentry>
335 </variablelist></refsect2>
336 <refsect2 id="G-WIN32-HAVE-WIDECHAR-API--CAPS" role="macro" condition="since:2.6">
337 <title>G_WIN32_HAVE_WIDECHAR_API()</title>
338 <indexterm zone="G-WIN32-HAVE-WIDECHAR-API--CAPS" role="2.6"><primary sortas="WIN32_HAVE_WIDECHAR_API">G_WIN32_HAVE_WIDECHAR_API</primary></indexterm><programlisting>#define G_WIN32_HAVE_WIDECHAR_API() TRUE
339 </programlisting>
340 <para>
341 On Windows, this macro defines an expression which evaluates to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>
342 if the code is running on a version of Windows where the wide
343 character versions of the Win32 API functions, and the wide chaacter
344 versions of the C library functions work. (They are always present in
345 the DLLs, but don't work on Windows 9x and Me.)
346 </para>
347 <para>
348 On non-Windows platforms, it is not defined.
349 </para><para role="since">Since 2.6</para></refsect2>
350 <refsect2 id="G-WIN32-IS-NT-BASED--CAPS" role="macro" condition="since:2.6">
351 <title>G_WIN32_IS_NT_BASED()</title>
352 <indexterm zone="G-WIN32-IS-NT-BASED--CAPS" role="2.6"><primary sortas="WIN32_IS_NT_BASED">G_WIN32_IS_NT_BASED</primary></indexterm><programlisting>#define G_WIN32_IS_NT_BASED() TRUE
353 </programlisting>
354 <para>
355 On Windows, this macro defines an expression which evaluates to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>
356 if the code is running on an NT-based Windows operating system.
357 </para>
358 <para>
359 On non-Windows platforms, it is not defined.
360 </para><para role="since">Since 2.6</para></refsect2>
361
362 </refsect1>
363
364
365
366
367 </refentry>