/src/wrappers/glib/library/utilities/glib_windows_compatibility_functions.e

  1deferred class GLIB_WINDOWS_COMPATIBILITY_FUNCTIONS
  2
  3--    Windows Compatibility Functions
  4
  5--    Windows Compatibility Functions -- UNIX emulation on Windows.
  6
  7-- Synopsis
  8
  9
 10--  #include <glib.h>
 11
 12
 13--  #define     MAXPATHLEN
 14--  #define     pipe                            (phandles)
 15--  gchar*      g_win32_error_message           (gint error);
 16--  gchar*      g_win32_getlocale               (void);
 17--  gchar*      g_win32_get_package_installation_directory
 18--                                              (gchar *package,
 19--                                               gchar *dll_name);
 20--  gchar*      g_win32_get_package_installation_subdirectory
 21--                                              (gchar *package,
 22--                                               gchar *dll_name,
 23--                                               gchar *subdir);
 24--  guint       g_win32_get_windows_version     (void);
 25--  gchar*      g_win32_locale_filename_from_utf8
 26--                                              (const gchar *utf8filename);
 27--  #define     G_WIN32_DLLMAIN_FOR_DLL_NAME    (static, dll_name)
 28--  #define     G_WIN32_HAVE_WIDECHAR_API       ()
 29--  #define     G_WIN32_IS_NT_BASED             ()
 30
 31
 32-- Description
 33
 34--    These functions provide some level of UNIX emulation on the Windows platform. If
 35--    your application really needs the POSIX APIs, we suggest you try the Cygwin
 36--    project.
 37
 38-- Details
 39
 40--   MAXPATHLEN
 41
 42--  #define MAXPATHLEN 1024
 43
 44--    Provided for UNIX emulation on Windows; equivalent to UNIX macro MAXPATHLEN,
 45--    which is the maximum length of a filename (including full path).
 46
 47--    ---------------------------------------------------------------------------------
 48
 49--   pipe()
 50
 51--  #define pipe(phandles)  _pipe (phandles, 4096, _O_BINARY)
 52
 53--    Provided for UNIX emulation on Windows; see documentation for pipe() in any UNIX
 54--    manual.
 55
 56--    phandles : file descriptors, the first one for reading, the second one for
 57--               writing.
 58
 59--    ---------------------------------------------------------------------------------
 60
 61--   g_win32_error_message ()
 62
 63--  gchar*      g_win32_error_message           (gint error);
 64
 65--    Translate a Win32 error code (as returned by GetLastError()) into the
 66--    corresponding message. The message is either language neutral, or in the thread's
 67--    language, or the user's language, the system's language, or US English (see docs
 68--    for FormatMessage()). The returned string is in UTF-8. It should be deallocated
 69--    with g_free().
 70
 71--    error :   error code.
 72--    Returns : newly-allocated error message
 73
 74--    ---------------------------------------------------------------------------------
 75
 76--   g_win32_getlocale ()
 77
 78--  gchar*      g_win32_getlocale               (void);
 79
 80--    The setlocale() function in the Microsoft C library uses locale names of the form
 81--    "English_United States.1252" etc. We want the UNIXish standard form "en_US",
 82--    "zh_TW" etc. This function gets the current thread locale from Windows - without
 83--    any encoding info - and returns it as a string of the above form for use in
 84--    forming file names etc. The returned string should be deallocated with g_free().
 85
 86--    Returns : newly-allocated locale name.
 87
 88--    ---------------------------------------------------------------------------------
 89
 90--   g_win32_get_package_installation_directory ()
 91
 92--  gchar*      g_win32_get_package_installation_directory
 93--                                              (gchar *package,
 94--                                               gchar *dll_name);
 95
 96--    Try to determine the installation directory for a software package. Typically
 97--    used by GNU software packages.
 98
 99--    package should be a short identifier for the package. Typically it is the same
100--    identifier as used for GETTEXT_PACKAGE in software configured according to GNU
101--    standards. The function first looks in the Windows Registry for the value
102--    #InstallationDirectory in the key #HKLM\Software\package, and if that value
103--    exists and is a string, returns that.
104
105--    If package is NULL, or the above value isn't found in the Registry, but dll_name
106--    is non-NULL, it should name a DLL loaded into the current process. Typically that
107--    would be the name of the DLL calling this function, looking for its installation
108--    directory. The function then asks Windows what directory that DLL was loaded
109--    from. If that directory's last component is "bin" or "lib", the parent directory
110--    is returned, otherwise the directory itself. If that DLL isn't loaded, the
111--    function proceeds as if dll_name was NULL.
112
113--    If both package and dll_name are NULL, the directory from where the main
114--    executable of the process was loaded is used instead in the same way as above.
115
116--    package :  An identifier for a software package, or NULL, in UTF-8
117--    dll_name : The name of a DLL that a package provides, or NULL, in UTF-8
118--    Returns :  a string containing the installation directory for package. The string
119--               is in the GLib file name encoding, i.e. UTF-8 on Windows. The return
120--               value should be freed with g_free() when not needed any longer.
121
122--    ---------------------------------------------------------------------------------
123
124--   g_win32_get_package_installation_subdirectory ()
125
126--  gchar*      g_win32_get_package_installation_subdirectory
127--                                              (gchar *package,
128--                                               gchar *dll_name,
129--                                               gchar *subdir);
130
131--    Returns a newly-allocated string containing the path of the subdirectory subdir
132--    in the return value from calling g_win32_get_package_installation_directory()
133--    with the package and dll_name parameters.
134
135--    package :  An identifier for a software package, in UTF-8, or NULL
136--    dll_name : The name of a DLL that a package provides, in UTF-8, or NULL
137--    subdir :   A subdirectory of the package installation directory, also in UTF-8
138--    Returns :  a string containing the complete path to subdir inside the
139--               installation directory of package. The returned string is in the GLib
140--               file name encoding, i.e. UTF-8 on Windows. The return value should be
141--               freed with g_free() when no longer needed.
142
143--    ---------------------------------------------------------------------------------
144
145--   g_win32_get_windows_version ()
146
147--  guint       g_win32_get_windows_version     (void);
148
149--    Returns version information for the Windows operating system the code is running
150--    on. See MSDN documentation for the GetVersion() function. To summarize, the most
151--    significant bit is one on Win9x, and zero on NT-based systems. The least
152--    significant byte is 4 on Windows NT 4, 5 on Windows XP. Software that needs
153--    really detailled version and feature information should use Win32 API like
154--    GetVersionEx() and VerifyVersionInfo().
155
156--    If there is an environment variable G_WIN32_PRETEND_WIN9X defined (with any
157--    value), this function always returns a version code for Windows 9x. This is
158--    mainly an internal debugging aid for GTK+ and GLib developers, to be able to
159--    check the code paths for Windows 9x.
160
161--    Returns : The version information.
162
163--    Since 2.6
164
165--    ---------------------------------------------------------------------------------
166
167--   g_win32_locale_filename_from_utf8 ()
168
169--  gchar*      g_win32_locale_filename_from_utf8
170--                                              (const gchar *utf8filename);
171
172--    Converts a filename from UTF-8 to the system codepage.
173
174--    On NT-based Windows, on NTFS file systems, file names are in Unicode. It is quite
175--    possible that Unicode file names contain characters not representable in the
176--    system codepage. (For instance, Greek or Cyrillic characters on Western European
177--    or US Windows installations, or various less common CJK characters on CJK Windows
178--    installations.)
179
180--    In such a case, and if the filename refers to an existing file, and the file
181--    system stores alternate short (8.3) names for directory entries, the short form
182--    of the filename is returned. Note that the "short" name might in fact be longer
183--    than the Unicode name if the Unicode name has very short pathname components
184--    containing non-ASCII characters. If no system codepage name for the file is
185--    possible, NULL is returned.
186
187--    The return value is dynamically allocated and should be freed with g_free() when
188--    no longer needed.
189
190--    utf8filename : a UTF-8 encoded filename.
191--    Returns :      The converted filename, or NULL on conversion failure and lack of
192--                   short names.
193
194--    Since 2.8
195
196--    ---------------------------------------------------------------------------------
197
198--   G_WIN32_DLLMAIN_FOR_DLL_NAME()
199
200--  #define     G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)
201
202--    On Windows, this macro defines a DllMain() function that stores the actual DLL
203--    name that the code being compiled will be included in.
204
205--    On non-Windows platforms, expands to nothing.
206
207--    static :   empty or "static".
208--    dll_name : the name of the (pointer to the) char array where the DLL name will be
209--               stored. If this is used, you must also include windows.h. If you need
210--               a more complex DLL entry point function, you cannot use this.
211
212--    ---------------------------------------------------------------------------------
213
214--   G_WIN32_HAVE_WIDECHAR_API()
215
216--  #define G_WIN32_HAVE_WIDECHAR_API() (G_WIN32_IS_NT_BASED ())
217
218--    On Windows, this macro defines an expression which evaluates to TRUE if the code
219--    is running on a version of Windows where the wide character versions of the Win32
220--    API functions, and the wide chaacter versions of the C library functions work.
221--    (They are always present in the DLLs, but don't work on Windows 9x and Me.)
222
223--    On non-Windows platforms, it is not defined.
224
225--    Since 2.6
226
227--    ---------------------------------------------------------------------------------
228
229--   G_WIN32_IS_NT_BASED()
230
231--  #define G_WIN32_IS_NT_BASED() (g_win32_get_windows_version () < 0x80000000)
232
233--    On Windows, this macro defines an expression which evaluates to TRUE if the code
234--    is running on an NT-based Windows operating system.
235
236--    On non-Windows platforms, it is not defined.
237
238--    Since 2.6
239
240end -- class GLIB_WINDOWS_COMPATIBILITY_FUNCTIONS