S60 3rd Edition API Reference: prtypes.h Source File

prtypes.h

Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* 
00003  * The contents of this file are subject to the Mozilla Public
00004  * License Version 1.1 (the "License"); you may not use this file
00005  * except in compliance with the License. You may obtain a copy of
00006  * the License at http://www.mozilla.org/MPL/
00007  * 
00008  * Software distributed under the License is distributed on an "AS
00009  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
00010  * implied. See the License for the specific language governing
00011  * rights and limitations under the License.
00012  * 
00013  * The Original Code is the Netscape Portable Runtime (NSPR).
00014  * 
00015  * The Initial Developer of the Original Code is Netscape
00016  * Communications Corporation.  Portions created by Netscape are 
00017  * Copyright (C) 1998-2000 Netscape Communications Corporation.  All
00018  * Rights Reserved.
00019  * 
00020  * Contributor(s):
00021  *    Portions Copyright (c) 2004-2006, Nokia Corporation
00022  *
00023  * 
00024  * Alternatively, the contents of this file may be used under the
00025  * terms of the GNU General Public License Version 2 or later (the
00026  * "GPL"), in which case the provisions of the GPL are applicable 
00027  * instead of those above.  If you wish to allow use of your 
00028  * version of this file only under the terms of the GPL and not to
00029  * allow others to use your version of this file under the MPL,
00030  * indicate your decision by deleting the provisions above and
00031  * replace them with the notice and other provisions required by
00032  * the GPL.  If you do not delete the provisions above, a recipient
00033  * may use your version of this file under either the MPL or the
00034  * GPL.
00035  */
00036 
00037 /* NOTES:
00038  * Nokia modified this file, by changing certain variables for the purpose of
00039  * porting the file to the Symbian platform on May 1st, 2004.
00040  */
00041 
00042 
00043 /*
00044 ** File:                prtypes.h
00045 ** Description: Definitions of NSPR's basic types
00046 **
00047 ** Prototypes and macros used to make up for deficiencies in ANSI environments
00048 ** that we have found.
00049 **
00050 ** Since we do not wrap <stdlib.h> and all the other standard headers, authors
00051 ** of portable code will not know in general that they need these definitions.
00052 ** Instead of requiring these authors to find the dependent uses in their code
00053 ** and take the following steps only in those C files, we take steps once here
00054 ** for all C files.
00055 **/
00056 
00057 #ifndef prtypes_h___
00058 #define prtypes_h___
00059 
00060 #ifdef MDCPUCFG
00061 #include MDCPUCFG
00062 #else
00063 #include "prcpucfg.h"
00064 #endif
00065 
00066 #include <stddef.h>
00067 
00068 /***********************************************************************
00069 ** MACROS:      PR_EXTERN
00070 **              PR_IMPLEMENT
00071 ** DESCRIPTION:
00072 **      These are only for externally visible routines and globals.  For
00073 **      internal routines, just use "extern" for type checking and that
00074 **      will not export internal cross-file or forward-declared symbols.
00075 **      Define a macro for declaring procedures return types. We use this to
00076 **      deal with windoze specific type hackery for DLL definitions. Use
00077 **      PR_EXTERN when the prototype for the method is declared. Use
00078 **      PR_IMPLEMENT for the implementation of the method.
00079 **
00080 ** Example:
00081 **   in dowhim.h
00082 **     PR_EXTERN( void ) DoWhatIMean( void );
00083 **   in dowhim.c
00084 **     PR_IMPLEMENT( void ) DoWhatIMean( void ) { return; }
00085 **
00086 **
00087 ***********************************************************************/
00088 #if defined(WIN32)
00089 
00090 #if defined(__GNUC__)
00091 #undef _declspec
00092 #define _declspec(x) __declspec(x)
00093 #endif
00094 
00095 #define PR_EXPORT(__type) extern _declspec(dllexport) __type
00096 #define PR_EXPORT_DATA(__type) extern _declspec(dllexport) __type
00097 #define PR_IMPORT(__type) _declspec(dllimport) __type
00098 #define PR_IMPORT_DATA(__type) _declspec(dllimport) __type
00099 
00100 #define PR_EXTERN(__type) extern _declspec(dllexport) __type
00101 #define PR_IMPLEMENT(__type) _declspec(dllexport) __type
00102 #define PR_EXTERN_DATA(__type) extern _declspec(dllexport) __type
00103 #define PR_IMPLEMENT_DATA(__type) _declspec(dllexport) __type
00104 
00105 #define PR_CALLBACK
00106 #define PR_CALLBACK_DECL
00107 #define PR_STATIC_CALLBACK(__x) static __x
00108 
00109 #elif defined(XP_BEOS)
00110 
00111 #define PR_EXPORT(__type) extern __declspec(dllexport) __type
00112 #define PR_EXPORT_DATA(__type) extern __declspec(dllexport) __type
00113 #define PR_IMPORT(__type) extern __declspec(dllexport) __type
00114 #define PR_IMPORT_DATA(__type) extern __declspec(dllexport) __type
00115 
00116 #define PR_EXTERN(__type) extern __declspec(dllexport) __type
00117 #define PR_IMPLEMENT(__type) __declspec(dllexport) __type
00118 #define PR_EXTERN_DATA(__type) extern __declspec(dllexport) __type
00119 #define PR_IMPLEMENT_DATA(__type) __declspec(dllexport) __type
00120 
00121 #define PR_CALLBACK
00122 #define PR_CALLBACK_DECL
00123 #define PR_STATIC_CALLBACK(__x) static __x
00124 
00125 #elif defined(WIN16)
00126 
00127 #define PR_CALLBACK_DECL        __cdecl
00128 
00129 #if defined(_WINDLL)
00130 #define PR_EXPORT(__type) extern __type _cdecl _export _loadds
00131 #define PR_IMPORT(__type) extern __type _cdecl _export _loadds
00132 #define PR_EXPORT_DATA(__type) extern __type _export
00133 #define PR_IMPORT_DATA(__type) extern __type _export
00134 
00135 #define PR_EXTERN(__type) extern __type _cdecl _export _loadds
00136 #define PR_IMPLEMENT(__type) __type _cdecl _export _loadds
00137 #define PR_EXTERN_DATA(__type) extern __type _export
00138 #define PR_IMPLEMENT_DATA(__type) __type _export
00139 
00140 #define PR_CALLBACK             __cdecl __loadds
00141 #define PR_STATIC_CALLBACK(__x) static __x PR_CALLBACK
00142 
00143 #else /* this must be .EXE */
00144 #define PR_EXPORT(__type) extern __type _cdecl _export
00145 #define PR_IMPORT(__type) extern __type _cdecl _export
00146 #define PR_EXPORT_DATA(__type) extern __type _export
00147 #define PR_IMPORT_DATA(__type) extern __type _export
00148 
00149 #define PR_EXTERN(__type) extern __type _cdecl _export
00150 #define PR_IMPLEMENT(__type) __type _cdecl _export
00151 #define PR_EXTERN_DATA(__type) extern __type _export
00152 #define PR_IMPLEMENT_DATA(__type) __type _export
00153 
00154 #define PR_CALLBACK             __cdecl __loadds
00155 #define PR_STATIC_CALLBACK(__x) __x PR_CALLBACK
00156 #endif /* _WINDLL */
00157 
00158 #elif defined(XP_MAC)
00159 
00160 #define PR_EXPORT(__type) extern __declspec(export) __type
00161 #define PR_EXPORT_DATA(__type) extern __declspec(export) __type
00162 #define PR_IMPORT(__type) extern __declspec(export) __type
00163 #define PR_IMPORT_DATA(__type) extern __declspec(export) __type
00164 
00165 #define PR_EXTERN(__type) extern __declspec(export) __type
00166 #define PR_IMPLEMENT(__type) __declspec(export) __type
00167 #define PR_EXTERN_DATA(__type) extern __declspec(export) __type
00168 #define PR_IMPLEMENT_DATA(__type) __declspec(export) __type
00169 
00170 #define PR_CALLBACK
00171 #define PR_CALLBACK_DECL
00172 #define PR_STATIC_CALLBACK(__x) static __x
00173 
00174 #elif defined(XP_OS2_VACPP) 
00175 
00176 #define PR_EXPORT(__type) extern __type
00177 #define PR_EXPORT_DATA(__type) extern __type
00178 #define PR_IMPORT(__type) extern __type
00179 #define PR_IMPORT_DATA(__type) extern __type
00180 
00181 #define PR_EXTERN(__type) extern __type
00182 #define PR_IMPLEMENT(__type) __type
00183 #define PR_EXTERN_DATA(__type) extern __type
00184 #define PR_IMPLEMENT_DATA(__type) __type
00185 #define PR_CALLBACK _Optlink
00186 #define PR_CALLBACK_DECL
00187 #define PR_STATIC_CALLBACK(__x) static __x PR_CALLBACK
00188 
00189 #else /* Unix */
00190 
00191 #define PR_EXPORT(__type) extern __type
00192 #define PR_EXPORT_DATA(__type) extern __type
00193 #define PR_IMPORT(__type) extern __type
00194 #define PR_IMPORT_DATA(__type) extern __type
00195 
00196 #define PR_EXTERN(__type) extern __type
00197 #define PR_IMPLEMENT(__type) __type
00198 #define PR_EXTERN_DATA(__type) extern __type
00199 #define PR_IMPLEMENT_DATA(__type) __type
00200 #define PR_CALLBACK
00201 #define PR_CALLBACK_DECL
00202 #define PR_STATIC_CALLBACK(__x) static __x
00203 
00204 #endif
00205 
00206 #if defined(_NSPR_BUILD_)
00207 #define NSPR_API(__type) PR_EXPORT(__type)
00208 #define NSPR_DATA_API(__type) PR_EXPORT_DATA(__type)
00209 #else
00210 #define NSPR_API(__type) PR_IMPORT(__type)
00211 #define NSPR_DATA_API(__type) PR_IMPORT_DATA(__type)
00212 #endif
00213 
00214 /***********************************************************************
00215 ** MACROS:      PR_BEGIN_MACRO
00216 **              PR_END_MACRO
00217 ** DESCRIPTION:
00218 **      Macro body brackets so that macros with compound statement definitions
00219 **      behave syntactically more like functions when called.
00220 ***********************************************************************/
00221 #define PR_BEGIN_MACRO  do {
00222 #define PR_END_MACRO    } while (0)
00223 
00224 /***********************************************************************
00225 ** MACROS:      PR_BEGIN_EXTERN_C
00226 **              PR_END_EXTERN_C
00227 ** DESCRIPTION:
00228 **      Macro shorthands for conditional C++ extern block delimiters.
00229 ***********************************************************************/
00230 #ifdef __cplusplus
00231 #define PR_BEGIN_EXTERN_C       extern "C" {
00232 #define PR_END_EXTERN_C         }
00233 #else
00234 #define PR_BEGIN_EXTERN_C
00235 #define PR_END_EXTERN_C
00236 #endif
00237 
00238 /***********************************************************************
00239 ** MACROS:      PR_BIT
00240 **              PR_BITMASK
00241 ** DESCRIPTION:
00242 ** Bit masking macros.  XXX n must be <= 31 to be portable
00243 ***********************************************************************/
00244 #define PR_BIT(n)       ((PRUint32)1 << (n))
00245 #define PR_BITMASK(n)   (PR_BIT(n) - 1)
00246 
00247 /***********************************************************************
00248 ** MACROS:      PR_ROUNDUP
00249 **              PR_MIN
00250 **              PR_MAX
00251 **              PR_ABS
00252 ** DESCRIPTION:
00253 **      Commonly used macros for operations on compatible types.
00254 ***********************************************************************/
00255 #define PR_ROUNDUP(x,y) ((((x)+((y)-1))/(y))*(y))
00256 #define PR_MIN(x,y)     ((x)<(y)?(x):(y))
00257 #define PR_MAX(x,y)     ((x)>(y)?(x):(y))
00258 #define PR_ABS(x)       ((x)<0?-(x):(x))
00259 
00260 PR_BEGIN_EXTERN_C
00261 
00262 /************************************************************************
00263 ** TYPES:       PRUint8
00264 **              PRInt8
00265 ** DESCRIPTION:
00266 **  The int8 types are known to be 8 bits each. There is no type that
00267 **      is equivalent to a plain "char". 
00268 ************************************************************************/
00269 #if PR_BYTES_PER_BYTE == 1
00270 typedef unsigned char PRUint8;
00271 /*
00272 ** Some cfront-based C++ compilers do not like 'signed char' and
00273 ** issue the warning message:
00274 **     warning: "signed" not implemented (ignored)
00275 ** For these compilers, we have to define PRInt8 as plain 'char'.
00276 ** Make sure that plain 'char' is indeed signed under these compilers.
00277 */
00278 #if (defined(HPUX) && defined(__cplusplus) \
00279         && !defined(__GNUC__) && __cplusplus < 199707L) \
00280     || (defined(SCO) && defined(__cplusplus) \
00281         && !defined(__GNUC__) && __cplusplus == 1L)
00282 typedef char PRInt8;
00283 #else
00284 typedef signed char PRInt8;
00285 #endif
00286 #else
00287 #error No suitable type for PRInt8/PRUint8
00288 #endif
00289 
00290 /************************************************************************
00291  * MACROS:      PR_INT8_MAX
00292  *              PR_INT8_MIN
00293  *              PR_UINT8_MAX
00294  * DESCRIPTION:
00295  *  The maximum and minimum values of a PRInt8 or PRUint8.
00296 ************************************************************************/
00297 
00298 #define PR_INT8_MAX 127
00299 #define PR_INT8_MIN (-128)
00300 #define PR_UINT8_MAX 255U
00301 
00302 /************************************************************************
00303 ** TYPES:       PRUint16
00304 **              PRInt16
00305 ** DESCRIPTION:
00306 **  The int16 types are known to be 16 bits each. 
00307 ************************************************************************/
00308 #if PR_BYTES_PER_SHORT == 2
00309 typedef unsigned short PRUint16;
00310 typedef short PRInt16;
00311 #else
00312 #error No suitable type for PRInt16/PRUint16
00313 #endif
00314 
00315 /************************************************************************
00316  * MACROS:      PR_INT16_MAX
00317  *              PR_INT16_MIN
00318  *              PR_UINT16_MAX
00319  * DESCRIPTION:
00320  *  The maximum and minimum values of a PRInt16 or PRUint16.
00321 ************************************************************************/
00322 
00323 #define PR_INT16_MAX 32767
00324 #define PR_INT16_MIN (-32768)
00325 #define PR_UINT16_MAX 65535U
00326 
00327 /************************************************************************
00328 ** TYPES:       PRUint32
00329 **              PRInt32
00330 ** DESCRIPTION:
00331 **  The int32 types are known to be 32 bits each. 
00332 ************************************************************************/
00333 #if PR_BYTES_PER_INT == 4
00334 typedef unsigned int PRUint32;
00335 typedef int PRInt32;
00336 #define PR_INT32(x)  x
00337 #define PR_UINT32(x) x ## U
00338 #elif PR_BYTES_PER_LONG == 4
00339 typedef unsigned long PRUint32;
00340 typedef long PRInt32;
00341 #define PR_INT32(x)  x ## L
00342 #define PR_UINT32(x) x ## UL
00343 #else
00344 #error No suitable type for PRInt32/PRUint32
00345 #endif
00346 
00347 /************************************************************************
00348  * MACROS:      PR_INT32_MAX
00349  *              PR_INT32_MIN
00350  *              PR_UINT32_MAX
00351  * DESCRIPTION:
00352  *  The maximum and minimum values of a PRInt32 or PRUint32.
00353 ************************************************************************/
00354 
00355 #define PR_INT32_MAX PR_INT32(2147483647)
00356 #define PR_INT32_MIN (-PR_INT32_MAX - 1)
00357 #define PR_UINT32_MAX PR_UINT32(4294967295)
00358 
00359 /************************************************************************
00360 ** TYPES:       PRUint64
00361 **              PRInt64
00362 ** DESCRIPTION:
00363 **  The int64 types are known to be 64 bits each. Care must be used when
00364 **      declaring variables of type PRUint64 or PRInt64. Different hardware
00365 **      architectures and even different compilers have varying support for
00366 **      64 bit values. The only guaranteed portability requires the use of
00367 **      the LL_ macros (see prlong.h).
00368 ************************************************************************/
00369 #ifdef HAVE_LONG_LONG
00370 #if PR_BYTES_PER_LONG == 8
00371 typedef long PRInt64;
00372 typedef unsigned long PRUint64;
00373 #elif defined(WIN16)
00374 typedef __int64 PRInt64;
00375 typedef unsigned __int64 PRUint64;
00376 #elif defined(WIN32) && !defined(__GNUC__)
00377 typedef __int64  PRInt64;
00378 typedef unsigned __int64 PRUint64;
00379 #else
00380 typedef long long PRInt64;
00381 typedef unsigned long long PRUint64;
00382 #endif /* PR_BYTES_PER_LONG == 8 */
00383 #else  /* !HAVE_LONG_LONG */
00384 typedef struct {
00385 #ifdef IS_LITTLE_ENDIAN
00386     PRUint32 lo, hi;
00387 #else
00388     PRUint32 hi, lo;
00389 #endif
00390 } PRInt64;
00391 typedef PRInt64 PRUint64;
00392 #endif /* !HAVE_LONG_LONG */
00393 
00394 /************************************************************************
00395 ** TYPES:       PRUintn
00396 **              PRIntn
00397 ** DESCRIPTION:
00398 **  The PRIntn types are most appropriate for automatic variables. They are
00399 **      guaranteed to be at least 16 bits, though various architectures may
00400 **      define them to be wider (e.g., 32 or even 64 bits). These types are
00401 **      never valid for fields of a structure. 
00402 ************************************************************************/
00403 #if PR_BYTES_PER_INT >= 2
00404 typedef int PRIntn;
00405 typedef unsigned int PRUintn;
00406 #else
00407 #error 'sizeof(int)' not sufficient for platform use
00408 #endif
00409 
00410 /************************************************************************
00411 ** TYPES:       PRFloat64
00412 ** DESCRIPTION:
00413 **  NSPR's floating point type is always 64 bits. 
00414 ************************************************************************/
00415 typedef double          PRFloat64;
00416 
00417 /************************************************************************
00418 ** TYPES:       PRSize
00419 ** DESCRIPTION:
00420 **  A type for representing the size of objects. 
00421 ************************************************************************/
00422 typedef size_t PRSize;
00423 
00424 
00425 /************************************************************************
00426 ** TYPES:       PROffset32, PROffset64
00427 ** DESCRIPTION:
00428 **  A type for representing byte offsets from some location. 
00429 ************************************************************************/
00430 typedef PRInt32 PROffset32;
00431 typedef PRInt64 PROffset64;
00432 
00433 /************************************************************************
00434 ** TYPES:       PRPtrDiff
00435 ** DESCRIPTION:
00436 **  A type for pointer difference. Variables of this type are suitable
00437 **      for storing a pointer or pointer sutraction. 
00438 ************************************************************************/
00439 typedef ptrdiff_t PRPtrdiff;
00440 
00441 /************************************************************************
00442 ** TYPES:       PRUptrdiff
00443 ** DESCRIPTION:
00444 **  A type for pointer difference. Variables of this type are suitable
00445 **      for storing a pointer or pointer sutraction. 
00446 ************************************************************************/
00447 typedef unsigned long PRUptrdiff;
00448 
00449 /************************************************************************
00450 ** TYPES:       PRBool
00451 ** DESCRIPTION:
00452 **  Use PRBool for variables and parameter types. Use PR_FALSE and PR_TRUE
00453 **      for clarity of target type in assignments and actual arguments. Use
00454 **      'if (bool)', 'while (!bool)', '(bool) ? x : y' etc., to test booleans
00455 **      juast as you would C int-valued conditions. 
00456 ************************************************************************/
00457 typedef PRIntn PRBool;
00458 #define PR_TRUE 1
00459 #define PR_FALSE 0
00460 
00461 /************************************************************************
00462 ** TYPES:       PRPackedBool
00463 ** DESCRIPTION:
00464 **  Use PRPackedBOol within structs where bitfields are not desireable
00465 **      but minimum and consistant overhead matters.
00466 ************************************************************************/
00467 typedef PRUint8 PRPackedBool;
00468 
00469 /*
00470 ** Status code used by some routines that have a single point of failure or 
00471 ** special status return.
00472 */
00473 typedef enum { PR_FAILURE = -1, PR_SUCCESS = 0 } PRStatus;
00474 
00475 #ifdef MOZ_UNICODE
00476 /*
00477  * EXPERIMENTAL: This type may be removed in a future release.
00478  */
00479 #ifndef __PRUNICHAR__
00480 #define __PRUNICHAR__
00481 #if defined(WIN32) || defined(XP_MAC)
00482 typedef wchar_t PRUnichar;
00483 #else
00484 typedef PRUint16 PRUnichar;
00485 #endif
00486 #endif
00487 #endif /* MOZ_UNICODE */
00488 
00489 /*
00490 ** WARNING: The undocumented data types PRWord and PRUword are
00491 ** only used in the garbage collection and arena code.  Do not
00492 ** use PRWord and PRUword in new code.
00493 **
00494 ** A PRWord is an integer that is the same size as a void*.
00495 ** It implements the notion of a "word" in the Java Virtual
00496 ** Machine.  (See Sec. 3.4 "Words", The Java Virtual Machine
00497 ** Specification, Addison-Wesley, September 1996.
00498 ** http://java.sun.com/docs/books/vmspec/index.html.)
00499 */
00500 typedef long PRWord;
00501 typedef unsigned long PRUword;
00502 
00503 #if defined(NO_NSPR_10_SUPPORT)
00504 #else
00505 /********* ???????????????? FIX ME       ??????????????????????????? *****/
00506 /********************** Some old definitions until pr=>ds transition is done ***/
00507 /********************** Also, we are still using NSPR 1.0. GC ******************/
00508 /*
00509 ** Fundamental NSPR macros, used nearly everywhere.
00510 */
00511 
00512 #define PR_PUBLIC_API   PR_IMPLEMENT
00513 
00514 /*
00515 ** Macro body brackets so that macros with compound statement definitions
00516 ** behave syntactically more like functions when called.
00517 */
00518 #define NSPR_BEGIN_MACRO        do {
00519 #define NSPR_END_MACRO          } while (0)
00520 
00521 /*
00522 ** Macro shorthands for conditional C++ extern block delimiters.
00523 */
00524 #ifdef NSPR_BEGIN_EXTERN_C
00525 #undef NSPR_BEGIN_EXTERN_C
00526 #endif
00527 #ifdef NSPR_END_EXTERN_C
00528 #undef NSPR_END_EXTERN_C
00529 #endif
00530 
00531 #ifdef __cplusplus
00532 #define NSPR_BEGIN_EXTERN_C     extern "C" {
00533 #define NSPR_END_EXTERN_C       }
00534 #else
00535 #define NSPR_BEGIN_EXTERN_C
00536 #define NSPR_END_EXTERN_C
00537 #endif
00538 
00539 #ifdef XP_MAC
00540 #include "protypes.h"
00541 #else
00542 #include "obsolete/protypes.h"
00543 #endif
00544 
00545 /********* ????????????? End Fix me ?????????????????????????????? *****/
00546 #endif /* NO_NSPR_10_SUPPORT */
00547 
00548 PR_END_EXTERN_C
00549 
00550 #endif /* prtypes_h___ */
00551
Copyright © Nokia Corporation 2001-2007
Back to top