include/SDL_log.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@5221
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@9619
     3
  Copyright (C) 1997-2015 Sam Lantinga <slouken@libsdl.org>
slouken@5221
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
slouken@5221
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
slouken@5221
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@5221
    20
*/
slouken@5221
    21
slouken@5221
    22
/**
slouken@5221
    23
 *  \file SDL_log.h
slouken@7191
    24
 *
slouken@5221
    25
 *  Simple log messages with categories and priorities.
slouken@5221
    26
 *
slouken@5221
    27
 *  By default logs are quiet, but if you're debugging SDL you might want:
slouken@5221
    28
 *
slouken@5221
    29
 *      SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN);
slouken@5221
    30
 *
slouken@5221
    31
 *  Here's where the messages go on different platforms:
slouken@5221
    32
 *      Windows: debug output stream
slouken@5221
    33
 *      Android: log output
slouken@5221
    34
 *      Others: standard error output (stderr)
slouken@5221
    35
 */
slouken@5221
    36
slouken@5221
    37
#ifndef _SDL_log_h
slouken@5221
    38
#define _SDL_log_h
slouken@5221
    39
slouken@5221
    40
#include "SDL_stdinc.h"
slouken@5221
    41
slouken@5221
    42
#include "begin_code.h"
slouken@5221
    43
/* Set up for C function definitions, even when using C++ */
slouken@5221
    44
#ifdef __cplusplus
slouken@5221
    45
extern "C" {
slouken@5221
    46
#endif
slouken@5221
    47
slouken@5221
    48
slouken@5221
    49
/**
slouken@5221
    50
 *  \brief The maximum size of a log message
slouken@5221
    51
 *
slouken@5221
    52
 *  Messages longer than the maximum size will be truncated
slouken@5221
    53
 */
slouken@5221
    54
#define SDL_MAX_LOG_MESSAGE 4096
slouken@5221
    55
slouken@5221
    56
/**
slouken@5221
    57
 *  \brief The predefined log categories
slouken@5221
    58
 *
slouken@5221
    59
 *  By default the application category is enabled at the INFO level,
aschiffler@6717
    60
 *  the assert category is enabled at the WARN level, test is enabled
slouken@7191
    61
 *  at the VERBOSE level and all other categories are enabled at the
aschiffler@6717
    62
 *  CRITICAL level.
slouken@5221
    63
 */
slouken@5221
    64
enum
slouken@5221
    65
{
slouken@5221
    66
    SDL_LOG_CATEGORY_APPLICATION,
slouken@5221
    67
    SDL_LOG_CATEGORY_ERROR,
slouken@6616
    68
    SDL_LOG_CATEGORY_ASSERT,
slouken@5221
    69
    SDL_LOG_CATEGORY_SYSTEM,
slouken@5221
    70
    SDL_LOG_CATEGORY_AUDIO,
slouken@5221
    71
    SDL_LOG_CATEGORY_VIDEO,
slouken@5221
    72
    SDL_LOG_CATEGORY_RENDER,
slouken@5221
    73
    SDL_LOG_CATEGORY_INPUT,
aschiffler@6717
    74
    SDL_LOG_CATEGORY_TEST,
slouken@5221
    75
slouken@5221
    76
    /* Reserved for future SDL library use */
slouken@5221
    77
    SDL_LOG_CATEGORY_RESERVED1,
slouken@5221
    78
    SDL_LOG_CATEGORY_RESERVED2,
slouken@5221
    79
    SDL_LOG_CATEGORY_RESERVED3,
slouken@5221
    80
    SDL_LOG_CATEGORY_RESERVED4,
slouken@5221
    81
    SDL_LOG_CATEGORY_RESERVED5,
slouken@5221
    82
    SDL_LOG_CATEGORY_RESERVED6,
slouken@5221
    83
    SDL_LOG_CATEGORY_RESERVED7,
slouken@5221
    84
    SDL_LOG_CATEGORY_RESERVED8,
slouken@5221
    85
    SDL_LOG_CATEGORY_RESERVED9,
slouken@5221
    86
    SDL_LOG_CATEGORY_RESERVED10,
slouken@5221
    87
slouken@5221
    88
    /* Beyond this point is reserved for application use, e.g.
slouken@5221
    89
       enum {
slouken@5221
    90
           MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM,
slouken@5221
    91
           MYAPP_CATEGORY_AWESOME2,
slouken@5221
    92
           MYAPP_CATEGORY_AWESOME3,
slouken@5221
    93
           ...
slouken@5221
    94
       };
slouken@5221
    95
     */
slouken@5303
    96
    SDL_LOG_CATEGORY_CUSTOM
slouken@5221
    97
};
slouken@5221
    98
slouken@5221
    99
/**
slouken@5221
   100
 *  \brief The predefined log priorities
slouken@5221
   101
 */
slouken@5221
   102
typedef enum
slouken@5221
   103
{
slouken@5221
   104
    SDL_LOG_PRIORITY_VERBOSE = 1,
slouken@5221
   105
    SDL_LOG_PRIORITY_DEBUG,
slouken@5221
   106
    SDL_LOG_PRIORITY_INFO,
slouken@5221
   107
    SDL_LOG_PRIORITY_WARN,
slouken@5221
   108
    SDL_LOG_PRIORITY_ERROR,
slouken@5221
   109
    SDL_LOG_PRIORITY_CRITICAL,
slouken@5221
   110
    SDL_NUM_LOG_PRIORITIES
slouken@5221
   111
} SDL_LogPriority;
slouken@5221
   112
slouken@5221
   113
slouken@5221
   114
/**
slouken@5221
   115
 *  \brief Set the priority of all log categories
slouken@5221
   116
 */
slouken@5221
   117
extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
slouken@5221
   118
slouken@5221
   119
/**
slouken@5221
   120
 *  \brief Set the priority of a particular log category
slouken@5221
   121
 */
slouken@5221
   122
extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
slouken@5221
   123
                                                SDL_LogPriority priority);
slouken@5221
   124
slouken@5221
   125
/**
slouken@6038
   126
 *  \brief Get the priority of a particular log category
slouken@5221
   127
 */
slouken@5221
   128
extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
slouken@5221
   129
slouken@5221
   130
/**
slouken@5221
   131
 *  \brief Reset all priorities to default.
slouken@5221
   132
 *
slouken@5221
   133
 *  \note This is called in SDL_Quit().
slouken@5221
   134
 */
slouken@5221
   135
extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
slouken@5221
   136
slouken@5221
   137
/**
slouken@5221
   138
 *  \brief Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO
slouken@5221
   139
 */
slouken@8820
   140
extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
slouken@5221
   141
slouken@5221
   142
/**
slouken@5221
   143
 *  \brief Log a message with SDL_LOG_PRIORITY_VERBOSE
slouken@5221
   144
 */
slouken@8820
   145
extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
slouken@5221
   146
slouken@5221
   147
/**
slouken@5348
   148
 *  \brief Log a message with SDL_LOG_PRIORITY_DEBUG
slouken@5348
   149
 */
slouken@8820
   150
extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
slouken@5348
   151
slouken@5348
   152
/**
slouken@5221
   153
 *  \brief Log a message with SDL_LOG_PRIORITY_INFO
slouken@5221
   154
 */
slouken@8820
   155
extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
slouken@5221
   156
slouken@5221
   157
/**
slouken@5221
   158
 *  \brief Log a message with SDL_LOG_PRIORITY_WARN
slouken@5221
   159
 */
slouken@8820
   160
extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
slouken@5221
   161
slouken@5221
   162
/**
slouken@5221
   163
 *  \brief Log a message with SDL_LOG_PRIORITY_ERROR
slouken@5221
   164
 */
slouken@8820
   165
extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
slouken@5221
   166
slouken@5221
   167
/**
slouken@5221
   168
 *  \brief Log a message with SDL_LOG_PRIORITY_CRITICAL
slouken@5221
   169
 */
slouken@8820
   170
extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
slouken@5221
   171
slouken@5221
   172
/**
slouken@5221
   173
 *  \brief Log a message with the specified category and priority.
slouken@5221
   174
 */
slouken@5221
   175
extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
slouken@5221
   176
                                            SDL_LogPriority priority,
slouken@8820
   177
                                            SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
slouken@5221
   178
slouken@5221
   179
/**
slouken@5221
   180
 *  \brief Log a message with the specified category and priority.
slouken@5221
   181
 */
slouken@5221
   182
extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
slouken@5221
   183
                                             SDL_LogPriority priority,
slouken@5221
   184
                                             const char *fmt, va_list ap);
slouken@5221
   185
slouken@5235
   186
/**
slouken@5235
   187
 *  \brief The prototype for the log output function
slouken@5235
   188
 */
slouken@5235
   189
typedef void (*SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
slouken@5235
   190
slouken@5235
   191
/**
slouken@5235
   192
 *  \brief Get the current log output function.
slouken@5235
   193
 */
slouken@5235
   194
extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
slouken@5235
   195
slouken@5235
   196
/**
slouken@5235
   197
 *  \brief This function allows you to replace the default log output
slouken@5235
   198
 *         function with one of your own.
slouken@5235
   199
 */
slouken@5235
   200
extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
slouken@5235
   201
slouken@5221
   202
slouken@5221
   203
/* Ends C function definitions when using C++ */
slouken@5221
   204
#ifdef __cplusplus
slouken@5221
   205
}
slouken@5221
   206
#endif
slouken@5221
   207
#include "close_code.h"
slouken@5221
   208
slouken@5221
   209
#endif /* _SDL_log_h */
slouken@5221
   210
slouken@5221
   211
/* vi: set ts=4 sw=4 expandtab: */