include/SDL_system.h
author Ryan C. Gordon <icculus@icculus.org>
Thu, 28 May 2015 01:54:52 -0400
changeset 9671 0e1f57b051f4
parent 9619 b94b6d0bff0f
child 9998 f67cf37e9cd4
permissions -rw-r--r--
Windows GetBasePath should use GetModuleFileNameExW() and check for overflows.

Apparently you might get strange paths from GetModuleFileName(), such as
short path names or UNC filenames, so this avoids that problem. Since you have
to tapdance with linking different libraries and defining macros depending on
what Windows you plan to target, we dynamically load the API we need, which
works on all versions of Windows (on Win7, it'll load a compatibility wrapper
for the newer API location).

What a mess.

This also now does the right thing if there isn't enough space to store the
path, looping with a larger allocated buffer each try.

Fixes Bugzilla #2435.
slouken@8582
     1
/*
slouken@8582
     2
  Simple DirectMedia Layer
slouken@9619
     3
  Copyright (C) 1997-2015 Sam Lantinga <slouken@libsdl.org>
slouken@8582
     4
slouken@8582
     5
  This software is provided 'as-is', without any express or implied
slouken@8582
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@8582
     7
  arising from the use of this software.
slouken@8582
     8
slouken@8582
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@8582
    10
  including commercial applications, and to alter it and redistribute it
slouken@8582
    11
  freely, subject to the following restrictions:
slouken@8582
    12
slouken@8582
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@8582
    14
     claim that you wrote the original software. If you use this software
slouken@8582
    15
     in a product, an acknowledgment in the product documentation would be
slouken@8582
    16
     appreciated but is not required.
slouken@8582
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@8582
    18
     misrepresented as being the original software.
slouken@8582
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@8582
    20
*/
slouken@8582
    21
slouken@8582
    22
/**
slouken@8582
    23
 *  \file SDL_system.h
slouken@8582
    24
 *
slouken@8582
    25
 *  Include file for platform specific SDL API functions
slouken@8582
    26
 */
slouken@8582
    27
slouken@8582
    28
#ifndef _SDL_system_h
slouken@8582
    29
#define _SDL_system_h
slouken@8582
    30
slouken@8582
    31
#include "SDL_stdinc.h"
slouken@8582
    32
#include "SDL_keyboard.h"
slouken@8582
    33
#include "SDL_render.h"
slouken@8582
    34
#include "SDL_video.h"
slouken@8582
    35
slouken@8582
    36
#include "begin_code.h"
slouken@8582
    37
/* Set up for C function definitions, even when using C++ */
slouken@8582
    38
#ifdef __cplusplus
slouken@8582
    39
extern "C" {
slouken@8582
    40
#endif
slouken@8582
    41
slouken@8582
    42
slouken@8582
    43
/* Platform specific functions for Windows */
slouken@8582
    44
#ifdef __WIN32__
slouken@9597
    45
	
slouken@9597
    46
/**
slouken@9597
    47
   \brief Set a function that is called for every windows message, before TranslateMessage()
slouken@9597
    48
*/
slouken@9599
    49
typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam);
slouken@9599
    50
extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
slouken@8582
    51
philipp@9309
    52
/**
philipp@9309
    53
   \brief Returns the D3D9 adapter index that matches the specified display index.
philipp@9309
    54
slouken@8582
    55
   This adapter index can be passed to IDirect3D9::CreateDevice and controls
slouken@8582
    56
   on which monitor a full screen application will appear.
slouken@8582
    57
*/
slouken@8582
    58
extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex );
slouken@8582
    59
philipp@9309
    60
typedef struct IDirect3DDevice9 IDirect3DDevice9;
philipp@9309
    61
/**
philipp@9309
    62
   \brief Returns the D3D device associated with a renderer, or NULL if it's not a D3D renderer.
philipp@9309
    63
slouken@8582
    64
   Once you are done using the device, you should release it to avoid a resource leak.
slouken@8582
    65
 */
slouken@8582
    66
extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_RenderGetD3D9Device(SDL_Renderer * renderer);
slouken@8582
    67
philipp@9309
    68
/**
philipp@9309
    69
   \brief Returns the DXGI Adapter and Output indices for the specified display index.
philipp@9309
    70
slouken@8213
    71
   These can be passed to EnumAdapters and EnumOutputs respectively to get the objects
slouken@8213
    72
   required to create a DX10 or DX11 device and swap chain.
slouken@8213
    73
 */
slouken@8719
    74
extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex );
slouken@8213
    75
slouken@8582
    76
#endif /* __WIN32__ */
slouken@8582
    77
slouken@8582
    78
slouken@8582
    79
/* Platform specific functions for iOS */
slouken@8582
    80
#if defined(__IPHONEOS__) && __IPHONEOS__
slouken@8582
    81
slime73@9539
    82
#define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam)
slouken@8582
    83
extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
slime73@9539
    84
slime73@9539
    85
#define SDL_iOSSetEventPump(enabled) SDL_iPhoneSetEventPump(enabled)
slouken@8582
    86
extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled);
slouken@8582
    87
slouken@8582
    88
#endif /* __IPHONEOS__ */
slouken@8582
    89
slouken@8582
    90
slouken@8582
    91
/* Platform specific functions for Android */
slouken@8582
    92
#if defined(__ANDROID__) && __ANDROID__
slouken@8582
    93
philipp@9309
    94
/**
philipp@9309
    95
   \brief Get the JNI environment for the current thread
philipp@9309
    96
slouken@8582
    97
   This returns JNIEnv*, but the prototype is void* so we don't need jni.h
slouken@8582
    98
 */
slouken@8582
    99
extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv();
slouken@8582
   100
philipp@9309
   101
/**
philipp@9309
   102
   \brief Get the SDL Activity object for the application
philipp@9309
   103
slouken@8582
   104
   This returns jobject, but the prototype is void* so we don't need jni.h
slouken@8582
   105
   The jobject returned by SDL_AndroidGetActivity is a local reference.
slouken@8582
   106
   It is the caller's responsibility to properly release it
slouken@8582
   107
   (using env->Push/PopLocalFrame or manually with env->DeleteLocalRef)
slouken@8582
   108
 */
slouken@8582
   109
extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity();
slouken@8582
   110
philipp@9309
   111
/**
philipp@9309
   112
   See the official Android developer guide for more information:
slouken@8582
   113
   http://developer.android.com/guide/topics/data/data-storage.html
slouken@8582
   114
*/
slouken@8582
   115
#define SDL_ANDROID_EXTERNAL_STORAGE_READ   0x01
slouken@8582
   116
#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE  0x02
slouken@8582
   117
philipp@9309
   118
/**
philipp@9309
   119
   \brief Get the path used for internal storage for this application.
philipp@9309
   120
slouken@8582
   121
   This path is unique to your application and cannot be written to
slouken@8582
   122
   by other applications.
slouken@8582
   123
 */
slouken@8582
   124
extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath();
slouken@8582
   125
philipp@9309
   126
/**
philipp@9309
   127
   \brief Get the current state of external storage, a bitmask of these values:
slouken@8582
   128
    SDL_ANDROID_EXTERNAL_STORAGE_READ
slouken@8582
   129
    SDL_ANDROID_EXTERNAL_STORAGE_WRITE
philipp@9309
   130
slouken@8582
   131
   If external storage is currently unavailable, this will return 0.
slouken@8582
   132
*/
slouken@8582
   133
extern DECLSPEC int SDLCALL SDL_AndroidGetExternalStorageState();
slouken@8582
   134
philipp@9309
   135
/**
philipp@9309
   136
   \brief Get the path used for external storage for this application.
philipp@9309
   137
slouken@8582
   138
   This path is unique to your application, but is public and can be
slouken@8582
   139
   written to by other applications.
slouken@8582
   140
 */
slouken@8582
   141
extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath();
slouken@8582
   142
slouken@8582
   143
#endif /* __ANDROID__ */
slouken@8582
   144
slouken@8582
   145
/* Platform specific functions for WinRT */
slouken@8582
   146
#if defined(__WINRT__) && __WINRT__
slouken@8582
   147
slouken@8582
   148
/**
slouken@8582
   149
 *  \brief WinRT / Windows Phone path types
slouken@8582
   150
 */
slouken@8582
   151
typedef enum
slouken@8582
   152
{
slouken@8582
   153
    /** \brief The installed app's root directory.
slouken@8582
   154
        Files here are likely to be read-only. */
slouken@8582
   155
    SDL_WINRT_PATH_INSTALLED_LOCATION,
slouken@8582
   156
slouken@8582
   157
    /** \brief The app's local data store.  Files may be written here */
slouken@8582
   158
    SDL_WINRT_PATH_LOCAL_FOLDER,
slouken@8582
   159
slouken@8582
   160
    /** \brief The app's roaming data store.  Unsupported on Windows Phone.
slouken@8582
   161
        Files written here may be copied to other machines via a network
slouken@8582
   162
        connection.
slouken@8582
   163
    */
slouken@8582
   164
    SDL_WINRT_PATH_ROAMING_FOLDER,
slouken@8582
   165
slouken@8582
   166
    /** \brief The app's temporary data store.  Unsupported on Windows Phone.
slouken@8582
   167
        Files written here may be deleted at any time. */
slouken@8582
   168
    SDL_WINRT_PATH_TEMP_FOLDER
slouken@8582
   169
} SDL_WinRT_Path;
slouken@8582
   170
slouken@8582
   171
slouken@8582
   172
/**
slouken@8582
   173
 *  \brief Retrieves a WinRT defined path on the local file system
slouken@8582
   174
 *
slouken@8582
   175
 *  \note Documentation on most app-specific path types on WinRT
slouken@8582
   176
 *      can be found on MSDN, at the URL:
slouken@8582
   177
 *      http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
slouken@8582
   178
 *
slouken@8582
   179
 *  \param pathType The type of path to retrieve.
philipp@9309
   180
 *  \return A UCS-2 string (16-bit, wide-char) containing the path, or NULL
slouken@8582
   181
 *      if the path is not available for any reason.  Not all paths are
slouken@8582
   182
 *      available on all versions of Windows.  This is especially true on
slouken@8582
   183
 *      Windows Phone.  Check the documentation for the given
slouken@8582
   184
 *      SDL_WinRT_Path for more information on which path types are
slouken@8582
   185
 *      supported where.
slouken@8582
   186
 */
slouken@8582
   187
extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType);
slouken@8582
   188
slouken@8582
   189
/**
slouken@8582
   190
 *  \brief Retrieves a WinRT defined path on the local file system
slouken@8582
   191
 *
slouken@8582
   192
 *  \note Documentation on most app-specific path types on WinRT
slouken@8582
   193
 *      can be found on MSDN, at the URL:
slouken@8582
   194
 *      http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
slouken@8582
   195
 *
slouken@8582
   196
 *  \param pathType The type of path to retrieve.
philipp@9309
   197
 *  \return A UTF-8 string (8-bit, multi-byte) containing the path, or NULL
slouken@8582
   198
 *      if the path is not available for any reason.  Not all paths are
slouken@8582
   199
 *      available on all versions of Windows.  This is especially true on
slouken@8582
   200
 *      Windows Phone.  Check the documentation for the given
slouken@8582
   201
 *      SDL_WinRT_Path for more information on which path types are
slouken@8582
   202
 *      supported where.
slouken@8582
   203
 */
slouken@8582
   204
extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType);
slouken@8582
   205
slouken@8582
   206
#endif /* __WINRT__ */
slouken@8582
   207
slouken@8582
   208
/* Ends C function definitions when using C++ */
slouken@8582
   209
#ifdef __cplusplus
slouken@8582
   210
}
slouken@8582
   211
#endif
slouken@8582
   212
#include "close_code.h"
slouken@8582
   213
slouken@8582
   214
#endif /* _SDL_system_h */
slouken@8582
   215
slouken@8582
   216
/* vi: set ts=4 sw=4 expandtab: */