platform.h
author Ryan C. Gordon <icculus@icculus.org>
Tue, 25 Sep 2007 02:24:31 +0000
changeset 345 a476d19c5767
parent 339 357703dfb348
child 369 f6c0eff5a144
permissions -rw-r--r--
Documented some of the platform layer interfaces.
icculus@249
     1
/**
icculus@249
     2
 * MojoSetup; a portable, flexible installation application.
icculus@249
     3
 *
icculus@249
     4
 * Please see the file LICENSE.txt in the source's root directory.
icculus@249
     5
 *
icculus@249
     6
 *  This file written by Ryan C. Gordon.
icculus@249
     7
 */
icculus@249
     8
icculus@5
     9
#ifndef _INCL_PLATFORM_H_
icculus@5
    10
#define _INCL_PLATFORM_H_
icculus@5
    11
icculus@5
    12
#include "universal.h"
icculus@5
    13
icculus@5
    14
#ifdef __cplusplus
icculus@5
    15
extern "C" {
icculus@5
    16
#endif
icculus@5
    17
icculus@10
    18
// this is called by your mainline.
icculus@8
    19
int MojoSetup_main(int argc, char **argv);
icculus@5
    20
icculus@69
    21
// Caller must free returned string!
icculus@70
    22
char *MojoPlatform_appBinaryPath(void);
icculus@14
    23
icculus@234
    24
// Caller must free returned string!
icculus@299
    25
char *MojoPlatform_currentWorkingDir(void);
icculus@299
    26
icculus@299
    27
// Caller must free returned string!
icculus@234
    28
char *MojoPlatform_homedir(void);
icculus@234
    29
icculus@44
    30
uint32 MojoPlatform_ticks(void);
icculus@44
    31
icculus@64
    32
// Make current process kill itself immediately, without any sort of internal
icculus@64
    33
//  cleanup, like atexit() handlers or static destructors...the OS will have
icculus@64
    34
//  to sort out the freeing of any resources, and no more code in this
icculus@64
    35
//  process than necessary should run. This function does not return. Try to
icculus@64
    36
//  avoid calling this.
icculus@64
    37
void MojoPlatform_die(void);
icculus@64
    38
icculus@189
    39
// Delete a file from the physical filesystem. This should remove empty
icculus@189
    40
//  directories as well as files. Returns true on success, false on failure.
icculus@77
    41
boolean MojoPlatform_unlink(const char *fname);
icculus@77
    42
icculus@104
    43
// Resolve symlinks, relative paths, etc. Caller free()'s buffer. Returns
icculus@104
    44
//  NULL if path couldn't be resolved.
icculus@104
    45
char *MojoPlatform_realpath(const char *path);
icculus@104
    46
icculus@145
    47
// Create a symlink in the physical filesystem. (src) is the NAME OF THE LINK
icculus@145
    48
//  and (dst) is WHAT IT POINTS TO. This is backwards from the unix symlink()
icculus@145
    49
//  syscall! Returns true if link was created, false otherwise.
icculus@145
    50
boolean MojoPlatform_symlink(const char *src, const char *dst);
icculus@145
    51
icculus@330
    52
// Read the destination from symlink (linkname). Returns a pointer
icculus@330
    53
//  allocated with xmalloc() containing the linkdest on success, and NULL
icculus@330
    54
//  on failure. The caller is responsible for freeing the returned pointer!
icculus@330
    55
char *MojoPlatform_readlink(const char *linkname);
icculus@330
    56
icculus@345
    57
// !!! FIXME: we really can't do this in a 16-bit value...non-Unix platforms
icculus@345
    58
// !!! FIXME:  and Extended Attributes need more.
icculus@345
    59
// Create a directory in the physical filesystem, with (perms) permissions.
icculus@345
    60
//  returns true if directory is created, false otherwise.
icculus@283
    61
boolean MojoPlatform_mkdir(const char *path, uint16 perms);
icculus@145
    62
icculus@145
    63
// Move a file to a new name. This has to be a fast (if not atomic) operation,
icculus@145
    64
//  so if it would require a legitimate copy to another filesystem or device,
icculus@145
    65
//  this should fail, as the standard Unix rename() function does.
icculus@145
    66
// Returns true on successful rename, false otherwise.
icculus@145
    67
boolean MojoPlatform_rename(const char *src, const char *dst);
icculus@145
    68
icculus@345
    69
// Determine if dir/fname exists in the native filesystem. It doesn't matter
icculus@345
    70
//  if it's a directory, file, symlink, etc, we're just looking for the
icculus@345
    71
//  existance of the entry itself. (fname) may be NULL, in which case,
icculus@345
    72
//  (dir) contains the whole path, otherwise, the platform layer needs to
icculus@345
    73
//  build the path: (on Unix: dir/path, on Windows: dir\\path, etc).
icculus@345
    74
//  This is a convenience thing for the caller.
icculus@345
    75
// Returns true if path in question exists, false otherwise.
icculus@131
    76
boolean MojoPlatform_exists(const char *dir, const char *fname);
icculus@131
    77
icculus@345
    78
// Returns true if (fname) in the native filesystem is writable. If (fname)
icculus@345
    79
//  is a directory, this means that the contents of the directory can be
icculus@345
    80
//  added to (create files, delete files, etc). If (fname) is a file, this
icculus@345
    81
//  means that this process has write access to the file.
icculus@345
    82
// Returns false if (fname) isn't writable.
icculus@237
    83
boolean MojoPlatform_writable(const char *fname);
icculus@237
    84
icculus@345
    85
// Returns true if (dir) is a directory in the physical filesystem, false
icculus@345
    86
//  otherwise (including if (dir) doesn't exist). Don't follow symlinks.
icculus@237
    87
boolean MojoPlatform_isdir(const char *dir);
icculus@237
    88
icculus@345
    89
// Returns true if (fname) is a symlink in the physical filesystem, false
icculus@345
    90
//  otherwise (including if (fname) doesn't exist). Don't follow symlinks.
icculus@339
    91
boolean MojoPlatform_issymlink(const char *fname);
icculus@339
    92
icculus@345
    93
// Returns true if (fname) is a regular file in the physical filesystem, false
icculus@345
    94
//  otherwise (including if (fname) doesn't exist). Don't follow symlinks.
icculus@339
    95
boolean MojoPlatform_isfile(const char *fname);
icculus@339
    96
icculus@345
    97
// Returns size, in bytes, of the file (fname) in the physical filesystem.
icculus@345
    98
//  Return -1 if file is missing or not a file. Don't follow symlinks.
icculus@339
    99
int64 MojoPlatform_filesize(const char *fname);
icculus@339
   100
icculus@345
   101
// !!! FIXME: we really can't do this in a 16-bit value...non-Unix platforms
icculus@345
   102
// !!! FIXME:  and Extended Attributes need more.
icculus@339
   103
// !!! FIXME: comment me.
icculus@155
   104
boolean MojoPlatform_perms(const char *fname, uint16 *p);
icculus@155
   105
icculus@345
   106
// !!! FIXME: we really can't do this in a 16-bit value...non-Unix platforms
icculus@345
   107
// !!! FIXME:  and Extended Attributes need more.
icculus@155
   108
// !!! FIXME: comment me.
icculus@155
   109
boolean MojoPlatform_chmod(const char *fname, uint16 p);
icculus@155
   110
icculus@345
   111
// Try to locate a specific piece of media (usually an inserted CD or DVD).
icculus@345
   112
//  (uniquefile) is a path that should exist on the media; its presence
icculus@345
   113
//  should uniquely identify the media.
icculus@345
   114
// Returns the path of the media's mount point in the physical filesystem
icculus@345
   115
//  (something like "E:\\" on Windows or "/mnt/cdrom" on Unix), or NULL if
icculus@345
   116
//  the media isn't found (needed disc isn't inserted, etc).
icculus@345
   117
// Caller must free return value!
icculus@131
   118
char *MojoPlatform_findMedia(const char *uniquefile);
icculus@131
   119
icculus@339
   120
// Flag values for MojoPlatform_fopen().
icculus@339
   121
typedef enum
icculus@339
   122
{
icculus@339
   123
    MOJOFILE_READ=(1<<0),
icculus@339
   124
    MOJOFILE_WRITE=(1<<1),
icculus@339
   125
    MOJOFILE_CREATE=(1<<2),
icculus@339
   126
    MOJOFILE_EXCLUSIVE=(1<<3),
icculus@339
   127
    MOJOFILE_TRUNCATE=(1<<4),
icculus@339
   128
    MOJOFILE_APPEND=(1<<5),
icculus@339
   129
} MojoFileFlags;
icculus@339
   130
icculus@339
   131
typedef enum
icculus@339
   132
{
icculus@339
   133
    MOJOSEEK_SET,
icculus@339
   134
    MOJOSEEK_CURRENT,
icculus@339
   135
    MOJOSEEK_END
icculus@339
   136
} MojoFileSeek;
icculus@339
   137
icculus@345
   138
// !!! FIXME: we really can't do this in a 16-bit value...non-Unix platforms
icculus@345
   139
// !!! FIXME:  and Extended Attributes need more.
icculus@345
   140
// Open file (fname). This wraps a subset of the Unix open() syscall. Use
icculus@345
   141
//  MojoFileFlags for (flags). If creating a file, use (mode) for the new
icculus@345
   142
//  file's permissions.
icculus@345
   143
// Returns an opaque handle on success, NULL on error. Caller must free
icculus@345
   144
//  handle with MojoPlatform_close() when done with it.
icculus@339
   145
void *MojoPlatform_open(const char *fname, uint32 flags, uint16 mode);
icculus@345
   146
icculus@345
   147
// Read (bytes) bytes from (fd) into (buf). This wraps the Unix read() syscall.
icculus@345
   148
//  Returns number of bytes read, -1 on error.
icculus@339
   149
int64 MojoPlatform_read(void *fd, void *buf, uint32 bytes);
icculus@345
   150
icculus@345
   151
// Write (bytes) bytes from (buf) into (fd). This wraps the Unix write()
icculus@345
   152
//  syscall. Returns number of bytes read, -1 on error.
icculus@339
   153
int64 MojoPlatform_write(void *fd, const void *buf, uint32 bytes);
icculus@345
   154
icculus@345
   155
// Reports byte offset of file pointer in (fd), or -1 on error.
icculus@339
   156
int64 MojoPlatform_tell(void *fd);
icculus@345
   157
icculus@345
   158
// Seek to (offset) byte offset of file pointer in (fd), relative to (whence).
icculus@345
   159
//  This wraps the Unix lseek() syscall. Returns byte offset from the start
icculus@345
   160
//  of the file, -1 on error.
icculus@339
   161
int64 MojoPlatform_seek(void *fd, int64 offset, MojoFileSeek whence);
icculus@345
   162
icculus@345
   163
// Get the size, in bytes, of a file, referenced by its opaque handle.
icculus@345
   164
//  (This pulls the data through an fstat() on Unix.) Retuns -1 on error.
icculus@339
   165
int64 MojoPlatform_flen(void *fd);
icculus@345
   166
icculus@345
   167
// Force any pending data to disk, returns true on success, false if there
icculus@345
   168
//  was an i/o error.
icculus@339
   169
boolean MojoPlatform_flush(void *fd);
icculus@345
   170
icculus@345
   171
// Free any resources associated with (fd), flushing any pending data to disk,
icculus@345
   172
//  and closing the file. (fd) becomes invalid after this call returns
icculus@345
   173
//  successfully. This wraps the Unix close() syscall. Returns true on
icculus@345
   174
//  success, false on i/o error.
icculus@339
   175
boolean MojoPlatform_close(void *fd);
icculus@339
   176
icculus@338
   177
// Enumerate a directory. Returns an opaque pointer that can be used with
icculus@338
   178
//  repeated calls to MojoPlatform_readdir() to enumerate the names of
icculus@338
   179
//  directory entries. Returns NULL on error. Non-NULL values should be passed
icculus@338
   180
//  to MojoPlatform_closedir() for cleanup when you are done with them.
icculus@338
   181
void *MojoPlatform_opendir(const char *dirname);
icculus@338
   182
icculus@338
   183
// Get the next entry in the directory. (dirhandle) is an opaque pointer
icculus@338
   184
//  returned by MojoPlatform_opendir(). Returns NULL if we're at the end of
icculus@338
   185
//  the directory, or a null-terminated UTF-8 string otherwise. The order of
icculus@338
   186
//  results are not guaranteed, and may change between two iterations.
icculus@338
   187
// Caller must free returned string!
icculus@338
   188
char *MojoPlatform_readdir(void *dirhandle);
icculus@338
   189
icculus@338
   190
// Clean up resources used by a directory enumeration. (dirhandle) is an
icculus@338
   191
//  opaque pointer returned by MojoPlatform_opendir(), and becomes invalid
icculus@338
   192
//  after this call.
icculus@338
   193
void MojoPlatform_closedir(void *dirhandle);
icculus@338
   194
icculus@283
   195
// Convert a string into a permissions bitmask. On Unix, this is currently
icculus@339
   196
//  expected to be an octal string like "0755", but may expect other forms
icculus@283
   197
//  in the future, and other platforms may need to interpret permissions
icculus@283
   198
//  differently. (str) may be NULL for defaults, and is considered valid.
icculus@283
   199
// If (str) is not valid, return a reasonable default and set (*valid) to
icculus@283
   200
//  false. Otherwise, set (*valid) to true and return the converted value.
icculus@283
   201
uint16 MojoPlatform_makePermissions(const char *str, boolean *valid);
icculus@283
   202
icculus@283
   203
// Return a default, sane set of permissions for a newly-created file.
icculus@283
   204
uint16 MojoPlatform_defaultFilePerms(void);
icculus@283
   205
icculus@283
   206
// Return a default, sane set of permissions for a newly-created directory.
icculus@283
   207
uint16 MojoPlatform_defaultDirPerms(void);
icculus@283
   208
icculus@82
   209
// Wrappers for Unix dlopen/dlsym/dlclose, sort of. Instead of a filename,
icculus@82
   210
//  these take a memory buffer for the library. If you can't load this
icculus@82
   211
//  directly in RAM, the platform should write it to a temporary file first,
icculus@82
   212
//  and deal with cleanup in MojoPlatform_dlclose(). The memory buffer must be
icculus@82
   213
//  dereferenced in MojoPlatform_dlopen(), as the caller may free() it upon
icculus@82
   214
//  return. Everything else works like the usual Unix calls.
icculus@82
   215
void *MojoPlatform_dlopen(const uint8 *img, size_t len);
icculus@77
   216
void *MojoPlatform_dlsym(void *lib, const char *sym);
icculus@77
   217
void MojoPlatform_dlclose(void *lib);
icculus@77
   218
icculus@299
   219
#if !SUPPORT_MULTIARCH
icculus@299
   220
#define MojoPlatform_switchBin(img, len)
icculus@299
   221
#else
icculus@299
   222
void MojoPlatform_switchBin(const uint8 *img, size_t len);
icculus@299
   223
#endif
icculus@299
   224
icculus@185
   225
// Put the calling process to sleep for at least (ticks) milliseconds.
icculus@185
   226
//  This is meant to yield the CPU while spinning in a loop that is polling
icculus@185
   227
//  for input, etc. Pumping the GUI event queue happens elsewhere, not here.
icculus@185
   228
void MojoPlatform_sleep(uint32 ticks);
icculus@131
   229
icculus@89
   230
// Put a line of text to the the system log, whatever that might be on a
icculus@89
   231
//  given platform. (str) is a complete line, but won't end with any newline
icculus@89
   232
//  characters. You should supply if needed.
icculus@89
   233
void MojoPlatform_log(const char *str);
icculus@89
   234
icculus@39
   235
// Get the current locale, in the format "xx_YY" where "xx" is the language
icculus@39
   236
//  (en, fr, de...) and "_YY" is the country. (_US, _CA, etc). The country
icculus@39
   237
//  can be omitted. Don't include encoding, it's always UTF-8 at this time.
icculus@39
   238
// Return true if locale is known, false otherwise.
icculus@39
   239
boolean MojoPlatform_locale(char *buf, size_t len);
icculus@39
   240
icculus@43
   241
boolean MojoPlatform_osType(char *buf, size_t len);
icculus@43
   242
boolean MojoPlatform_osVersion(char *buf, size_t len);
icculus@43
   243
icculus@43
   244
// Basic platform detection.
icculus@43
   245
#if PLATFORM_WINDOWS
icculus@43
   246
#define PLATFORM_NAME "windows"
icculus@43
   247
#elif PLATFORM_MACOSX
icculus@43
   248
#define PLATFORM_NAME "macosx"
icculus@43
   249
#elif PLATFORM_UNIX
icculus@43
   250
#define PLATFORM_NAME "unix"
icculus@98
   251
#elif PLATFORM_BEOS
icculus@98
   252
#define PLATFORM_NAME "beos"
icculus@43
   253
#else
icculus@82
   254
#error Unknown platform.
icculus@43
   255
#endif
icculus@43
   256
icculus@43
   257
// Basic architecture detection.
icculus@43
   258
icculus@43
   259
#if defined(__powerpc64__)
icculus@43
   260
#define PLATFORM_ARCH "powerpc64"
icculus@43
   261
#elif defined(__ppc__) || defined(__powerpc__) || defined(__POWERPC__)
icculus@43
   262
#define PLATFORM_ARCH "powerpc"
icculus@43
   263
#elif defined(__x86_64__) || defined(_M_X64)
icculus@43
   264
#define PLATFORM_ARCH "x86-64"
icculus@43
   265
#elif defined(__X86__) || defined(__i386__) || defined(i386) || defined (_M_IX86) || defined(__386__)
icculus@43
   266
#define PLATFORM_ARCH "x86"
icculus@43
   267
#else
icculus@43
   268
#error Unknown processor architecture.
icculus@43
   269
#endif
icculus@43
   270
icculus@339
   271
// Other basic truths...
icculus@339
   272
#if PLATFORM_WINDOWS
icculus@339
   273
#define MOJOPLATFORM_ENDLINE "\r\n"
icculus@339
   274
#else
icculus@339
   275
#define MOJOPLATFORM_ENDLINE "\n"
icculus@339
   276
#endif
icculus@339
   277
icculus@5
   278
#ifdef __cplusplus
icculus@5
   279
}
icculus@5
   280
#endif
icculus@5
   281
icculus@5
   282
#endif
icculus@5
   283
icculus@10
   284
// end of platform.h ...
icculus@5
   285