Mirrors_UI_SDK/MiniGUI
1
0
Fork 0
mirror of https://github.com/VincentWei/MiniGUI.git synced 2026-02-07 02:52:42 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

cleanup for Doxygen

Browse Source
This commit is contained in:
Vincent Wei
2019-04-11 10:54:17 +08:00
parent 2581fa4d18
commit dd6248e90e
4 changed files with 207 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
Doxyfile.ths
View File

@@ -38,7 +38,7 @@ PROJECT_NAME = "MiniGUI API Reference (MiniGUI-Threads)"
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = v3.2.0
PROJECT_NUMBER = v4.0.0
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
@@ -1288,7 +1288,7 @@ GENERATE_HTMLHELP = NO
# written to the html output directory.
# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
CHM_FILE =
CHM_FILE =
# The HHC_LOCATION tag can be used to specify the location (absolute path
# including file name) of the HTML help compiler (hhc.exe). If non-empty,
@@ -2073,6 +2073,7 @@ PREDEFINED = _MGRM_THREADS \
_MGMISC_SAVEBITMAP \
_MGHAVE_CURSOR \
_MGCHARSET_UNICODE \
_MGCOMPLEX_SCRIPTS \
_MGCTRL_STATIC \
_MGCTRL_SLEDIT \
_MGCTRL_BIDISLEDIT \

2
include/common.h
View File

@@ -727,7 +727,7 @@ typedef UINT_PTR LPARAM;
#define MAKEWORD16(low, high) ((WORD16)(((BYTE)(low)) | (((WORD16)((BYTE)(high))) << 8)))
/**
* \def MAKEWORD32(first, second, third, fourth)
* \def MAKEDWORD32(first, second, third, fourth)
* \brief Makes a WORD32 value with four bytes.
*
* \sa MAKEWORD16, FIRSTBYTE, SECONDBYTE, THIRDBYTE, FOURTHBYTE

138
include/gdi.h
View File

@@ -5849,7 +5849,7 @@ typedef Uint32 Uchar32;
/**
* \def ACHARTYPE_UNKNOWN
* \breif Unknown abstract character type.
* \brief Unknown abstract character type.
*/
#define ACHARTYPE_UNKNOWN 0
@@ -6063,7 +6063,7 @@ typedef enum {
* ScriptType: The script type of a UNICODE character.
*
* - SCRIPT_INVALID_CODE:
* a value never returned from UCharGetScriptType()
* a value never returned from UCharGetScriptType()
* - SCRIPT_COMMON: a character used by multiple different scripts
* - SCRIPT_INHERITED: a mark glyph that takes its script from the
* base glyph to which it is attached
@@ -6719,31 +6719,33 @@ typedef enum {
} LanguageCode;
/**
* LanuageCodeFromISO639s1:
* @iso639_1: An encoded language code in ISO639-1.
* \fn LanguageCode GUIAPI LanguageCodeFromISO639s1 (Uint16 iso639_1)
* \brief Get MiniGUI language code from an encoded ISO639-1 language code.
*
* Looks up the language code for ISO639-1. ISO639-1 assigns two-letter
* codes to languages. For example, the code for Arabic is 'ar'.
* This function accepts two letter codes encoded as a @Uint16 in a
* This function accepts two letter codes encoded as a Uint16 in a
* big-endian fashion. That is, the code expected for Arabic is
* 0x6172 (0x61 is ASCII code for 'a', 0x72 is ASCII code for 'r', etc).
*
* Returns: the language code for @iso639_1, or
* of %LANGCODE_unknown if @iso639_1 is invalid.
* \param iso639_1 An encoded language code in ISO639-1.
* \return The language code for \a iso639_1, or \a LANGCODE_unknown if
* \a iso639_1 is invalid.
*
* Since: 4.0.0
*/
MG_EXPORT LanguageCode GUIAPI LanguageCodeFromISO639s1 (Uint16 iso639_1);
/**
* LanguageCodeFromISO639s1Code:
* @iso639_1: A language code in ISO639-1.
* \fn LanguageCode GUIAPI LanguageCodeFromISO639s1Code(const char* iso639_1)
* \brief Get MiniGUI language code from an ISO639-1 language code string.
*
* Looks up the language code for ISO639-1. ISO639-1 assigns two-letter
* codes to languages. For example, the code for Arabic is 'ar'.
* codes to languages. For example, the code for Arabic is 'ar'.
*
* Returns: the language code for @iso639_1, or
* of %LANGCODE_unknown if @iso639_1 is invalid.
* \param iso639_1 A language code in ISO639-1.
* \return The language code for \a iso639_1, or \a LANGCODE_unknown if
* \a iso639_1 is invalid.
*
* Since: 4.0.0
*/
@@ -8613,7 +8615,7 @@ MG_EXPORT BidiJoiningType GUIAPI UCharGetJoiningType(Uchar32 uc);
/**
* \fn void GUIAPI UStrGetJoiningTypes(const Uchar32 *ucs, int nr_ucs,
* BidiJoiningType *joing_types)
* BidiJoiningType *joining_types)
* \brief Get joining types for a string of Unicode characters
*
* This function finds the joining types of an string of characters.
@@ -8630,7 +8632,7 @@ MG_EXPORT BidiJoiningType GUIAPI UCharGetJoiningType(Uchar32 uc);
* Since: 4.0.0
*/
MG_EXPORT void GUIAPI UStrGetJoiningTypes(const Uchar32 *ucs, int nr_ucs,
BidiJoiningType *joing_types);
BidiJoiningType *joining_types);
/**
* \fn BidiType GUIAPI UBidiGetParagraphDir(const BidiType *bidi_types, int len)
@@ -8725,7 +8727,7 @@ typedef void (*CB_REVERSE_ARRAY) (void* extra, int len, int pos);
* \fn BidiLevel GUIAPI UBidiReorderLine(Uint32 bidi_flags,
* const BidiType *bidi_types, int len, int off,
* ParagraphDir paragraph_dir, BidiLevel *embedding_levels,
* Uchar32 *visual_str, int *map,
* Uchar32 *visual_str, int *indices_map,
* void* extra, CB_REVERSE_ARRAY cb_reverse_extra)
* \brief Reorder a line of logical string to visual string.
*
@@ -8761,8 +8763,6 @@ typedef void (*CB_REVERSE_ARRAY) (void* extra, int len, int pos);
* \param bidi_flags The reorder flags.
* \param bidi_types the pointer to the BidiType array as returned by
* UStrGetBidiTypes()
* \param bracket_types The pointer to a BidiBracketType array which
* contains the bracket types as returned by UStrGetBracketTypes()
* \param len The length of the list.
* \param off The input offset of the beginning of the line in the paragraph.
* \param paragraph_dir The resolved paragraph base direction.
@@ -8851,7 +8851,7 @@ MG_EXPORT void GUIAPI UBidiJoinArabic(const BidiType *bidi_types,
BidiArabicProp *ar_props);
/**
* \fn void GUIAPI UBidiShapeArabic(Uint32 bidi_flags,
* \fn void GUIAPI UBidiShapeArabic(Uint32 shaping_flags,
* const BidiLevel *embedding_levels, int len,
* BidiArabicProp *ar_props, Uchar32 *ucs)
* \brief Do Arabic shaping.
@@ -8879,7 +8879,7 @@ MG_EXPORT void GUIAPI UBidiJoinArabic(const BidiType *bidi_types,
* \param embedding_levels input list of embedding levels, as returned by
* UBidiGetParagraphEmbeddingLevels().
* \param len The length of the string.
* \param arb_props The Arabic character properties as computed by
* \param ar_props The Arabic character properties as computed by
* UBidiJoinArabic().
* \param ucs The Uchar32 string to shape.
*
@@ -8893,8 +8893,8 @@ MG_EXPORT void GUIAPI UBidiShapeArabic(Uint32 shaping_flags,
/**
* \fn void GUIAPI UBidiShape(Uint32 shaping_flags,
const BidiLevel *embedding_levels, int len,
BidiArabicProp *ar_props, Uchar32* ucs)
* const BidiLevel *embedding_levels, int len,
* BidiArabicProp *ar_props, Uchar32* ucs)
* \brief Do bidi-aware shaping.
*
* This function does all shaping work that depends on the resolved embedding
@@ -8915,7 +8915,7 @@ MG_EXPORT void GUIAPI UBidiShapeArabic(Uint32 shaping_flags,
* \param embedding_levels input list of embedding levels, as returned by
* UBidiGetParagraphEmbeddingLevels().
* \param len The length of the string.
* \param arb_props The Arabic character properties as computed by
* \param ar_props The Arabic character properties as computed by
* UBidiJoinArabic().
* \param ucs The Uchar32 string to shape.
*
@@ -9198,7 +9198,7 @@ typedef Uint16 BreakOppo;
* Note that you are responsible for freeing the break opportunities array
* allocated by this function if it allocates the buffer.
*
* \param writing_system The writing system (script) identifier.
* \param lang_code The language code; not used so far, reserved for future.
* \param ctr The character transformation rule; see \a char_transform_rule.
* \param wbr The word breaking rule; see \a word_break_rules.
* \param lbp The line breaking policy; see \a line_break_policies.
@@ -9359,7 +9359,7 @@ MG_EXPORT int GUIAPI UCharFullyDecompose (Uchar32 ch, BOOL compat,
* \fn ScriptType GUIAPI UCharGetScriptType (Uchar32 ch)
*
* Looks up the script code for a particular character (as defined
* by Unicode Standard Annex #24). No check is made for @ch being a
* by Unicode Standard Annex #24). No check is made for \a ch being a
* valid Unicode character; if you pass in invalid character, the
* result is undefined.
*
@@ -9376,11 +9376,16 @@ MG_EXPORT ScriptType GUIAPI UCharGetScriptType (Uchar32 ch);
/**
* \fn Uint32 ScriptTypeToISO15924 (ScriptType script)
*
* Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter
* codes to scripts. For example, the code for Arabic is 'Arab'. The
* four letter codes are encoded as a @Uint32 by this function in a
* big-endian fashion. That is, the code returned for Arabic is
* 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
* Looks up the ISO15924 code for the specific ScriptType \a script.
* ISO15924 assigns four-letter codes to scripts. For example,
* the code for Arabic is 'Arab'. The four letter codes are encoded
* as a Uint32 by this function in a big-endian fashion.
* That is, the code returned for Arabic is 0x41726162 (0x41 is ASCII
* code for 'A', 0x72 is ASCII code for 'r', etc).
*
* See
* [Codes for the representation of names of scripts](https://www.unicode.org/iso15924/codelists.html)
* for details.
*
* \param script a Unicode script
*
@@ -9389,9 +9394,7 @@ MG_EXPORT ScriptType GUIAPI UCharGetScriptType (Uchar32 ch);
* ISO 15924 code 'Zzzz' (script code for UNKNOWN) if \a script
* is not understood.
*
* See
* [Codes for the representation of names of scripts](https://www.unicode.org/iso15924/codelists.html)
* for details.
* \sa ScriptTypeFromISO15924
*
* Since: 4.0.0
*/
@@ -9399,22 +9402,26 @@ MG_EXPORT Uint32 GUIAPI ScriptTypeToISO15924 (ScriptType script);
/**
* \fn ScriptType ScriptTypeFromISO15924 (Uint32 iso15924)
* \brief Get the ScriptType value from an encoded ISO15924 script code.
*
* Looks up the Unicode script type for @iso15924. ISO 15924 assigns four-letter
* codes to scripts. For example, the code for Arabic is 'Arab'.
* This function accepts four letter codes encoded as a @Uint32 in a
* big-endian fashion. That is, the code expected for Arabic is
* Looks up the Unicode script type for the specified encoded ISO15924
* script code \a iso15924. ISO 15924 assigns four-letter
* codes to scripts. For example, the code for Arabic is 'Arab'.
* This function accepts four letter codes encoded as a Uint32 in a
* big-endian fashion. That is, the code expected for Arabic is
* 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
*
* \param an encoded Unicode script code in ISO15924
* See
* [Codes for the representation of names of scripts](https://www.unicode.org/iso15924/codelists.html)
* for details.
*
* \param iso15924 an encoded Unicode script code in ISO15924.
*
* \return the Unicode script for \a iso15924, or
* of \a SCRIPT_INVALID_CODE if \a iso15924 is zero and
* \a SCRIPT_UNKNOWN if \a iso15924 is unknown.
*
* See
* [Codes for the representation of names of scripts](https://www.unicode.org/iso15924/codelists.html)
* for details.
* \sa ScriptTypeFromISO15924Code
*
* Since: 4.0.0
*/
@@ -9423,19 +9430,22 @@ MG_EXPORT ScriptType GUIAPI ScriptTypeFromISO15924 (Uint32 iso15924);
/**
* \fn ScriptType ScriptTypeFromISO15924Code (const char* iso15924)
*
* Looks up the Unicode script type for @iso15924. ISO 15924 assigns four-letter
* codes to scripts. For example, the code for Arabic is 'Arab'.
*
* \param iso15924 a Unicode script type code in ISO15924
*
* \returns the Unicode script for \a iso15924, or
* of \a SCRIPT_INVALID_CODE if \a iso15924 is zero and
* \a SCRIPT_UNKNOWN if \a iso15924 is unknown.
* Looks up the Unicode script type for the specified ISO15924 script code
* \a iso15924. ISO15924 assigns four-letter codes to scripts.
* For example, the code for Arabic is 'Arab'.
*
* See
* [Codes for the representation of names of scripts](https://www.unicode.org/iso15924/codelists.html)
* for details.
*
* \param iso15924 a Unicode script type code in ISO15924.
*
* \return the Unicode script for \a iso15924, or
* of \a SCRIPT_INVALID_CODE if \a iso15924 is zero and
* \a SCRIPT_UNKNOWN if \a iso15924 is unknown.
*
* \sa ScriptTypeFromISO15924
*
* Since: 4.0.0
*/
static inline ScriptType GUIAPI ScriptTypeFromISO15924Code (const char* iso15924)
@@ -9482,17 +9492,17 @@ MG_EXPORT UVerticalOrient GUIAPI UCharGetVerticalOrientation(Uchar32 uc);
* \brief Based on the script, base gravity, and policy, returns actual gravity
* to use in laying out a single glyph run.
*
* If @base_orient is %GLYPH_GRAVITY_AUTO, it is first replaced with the
* preferred orientation of @script. To get the preferred orientation of a script,
* pass %GLYPH_GRAVITY_AUTO and %GLYPH_GRAVITY_POLICY_STRONG in.
* If \a base_orient is \a GLYPH_GRAVITY_AUTO, it is first replaced with the
* preferred orientation of \a script. To get the preferred orientation of a script,
* pass \a GLYPH_GRAVITY_AUTO and \a GLYPH_GRAVITY_POLICY_STRONG in.
*
* \param script The script type to query
* \param vertical TRUE for vertical layout
* \param base_gravity The base gravity of the layout
* \param policy The gravity policy
*
* \param The resolved gravity suitable to use for a layout run of text
* with @script.
* \return The resolved gravity suitable to use for a layout run of text
* with \a script.
*
* Since: 4.0.0
*/
@@ -9513,8 +9523,8 @@ MG_EXPORT GlyphGravity GUIAPI ScriptGetGlyphGravity(ScriptType script,
* base gravity, whereas narrow/half-width characters are always
* rotated in vertical context.
*
* If @base_orient is %GLYPH_GRAVITY_AUTO, it is first replaced with the
* preferred gravity of @script.
* If \a base_orient is \a GLYPH_GRAVITY_AUTO, it is first replaced with the
* preferred gravity of \a script.
*
* \param script The script type to query
* \param vertical TRUE for vertical layout.
@@ -11477,7 +11487,7 @@ MG_EXPORT Achar32 GUIAPI GetShapedAChar (LOGFONT* logfont, const char* mchar,
* \brief Get the mirrored abstract character if possible.
*
* \param logfont The logical font.
* \param glyph The glyph value.
* \param chv The abstract character value.
* \param mirrored The buffer to store the mirrored Achar32 value if
* the multi-byte character has a mirrored character.
*
@@ -11502,9 +11512,9 @@ MG_EXPORT BOOL GUIAPI GetMirrorAChar (LOGFONT* logfont, Achar32 chv,
* This function retrieves the BIDI type of an abstract character.
*
* \param logfont The logical font.
* \param glyph_value The glyph value.
* \param chv The abstract character value.
*
* \return The BIDI type of the Achar32; BIDI_TYPE_INVALID on failure.
* \return The BIDI type of \a chv; BIDI_TYPE_INVALID on failure.
*
* \note This is an API of the legacy implementation of bidirectional algorithm.
* It is used to support text in ISO8859-6 and ISO8859-8 charsets
@@ -12096,8 +12106,6 @@ MG_EXPORT int GUIAPI GetGlyphInfo (LOGFONT* logfont, Glyph32 glyph_value,
* \param mstr The pointer to the multi-byte string.
* \param mstr_len The length of \a mstr in bytes.
* \param wsr The white space rule; see \a white_space_rules.
* \param ctr The character transformation rule;
* see \a char_transform_rule.
* \param uchars The pointer to a buffer to store the address of the
* Uchar32 array which contains the Unicode character values.
* \param nr_uchars The buffer to store the number of the allocated
@@ -12141,7 +12149,9 @@ MG_EXPORT Uchar32 GUIAPI AChar2UChar(LOGFONT* logfont, Achar32 chv);
* Only valid for UNICODE.
*
* \param logfont The LOGFONT object
* \param chs The array of LOGFONT character values.
* \param achs The array of the abstract character values.
* \param ucs The buffer to store the converted Uchar32 characters.
* \param n The length of the Achar32 array.
*
* \return The number of characters converted successfully.
*
@@ -12197,7 +12207,9 @@ MG_EXPORT BOOL GUIAPI UChar2AChar(LOGFONT* logfont, Uchar32 uc, Achar32* ac);
* Only valid for UNICODE.
*
* \param logfont The LOGFONT object
* \param chs The array of LOGFONT character values.
* \param ucs The array of the Unicode characters.
* \param acs The buffer to store the converted abstract characters.
* \param n The length of the Uchar32 array.
*
* \return The number of characters converted successfully.
*
@@ -13173,8 +13185,6 @@ MG_EXPORT BOOL DrawShapedGlyph(HDC hdc,
* \param y The buffer contained the y-corrdinate of the output position
* of the first glyph in the line. The y-corrdinate of the next line
* will be returned through this buffer as well.
* \param bounding The buffer to store the bounding rectangle of
* the line; can be NULL.
*
* \return The number of glyphs drawn.
*

231
include/minigui.h
View File

@@ -54,7 +54,6 @@
#include <stdio.h>
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
@@ -87,13 +86,13 @@ extern MG_EXPORT RECT g_rcScr;
/** @} end of rect_vars */
#ifdef _MGRM_PROCESSES
/**
* \defgroup lite_vars MiniGUI-Processes specific variables
* @{
*/
#ifdef _MGRM_PROCESSES
#include <sys/types.h>
/**
@@ -246,12 +245,21 @@ extern MG_EXPORT MG_Layer* mgTopmostLayer;
*/
extern MG_EXPORT MG_Layer* mgLayers;
#endif /* _MGRM_PROCESSES */
/** @} end of lite_vars */
#endif /* _MGRM_PROCESSES */
/** @} end of global_vars */
/**
* \addtogroup fns Functions
* @{
*/
/**
* \addtogroup global_fns Global/general functions
* @{
*/
/**
* \fn int GUIAPI InitGUI (int, const char **)
@@ -282,23 +290,13 @@ MG_EXPORT void GUIAPI TerminateGUI (int not_used);
**/
MG_EXPORT void GUIAPI MiniGUIPanic (int exitcode);
/**
* \addtogroup fns Functions
* @{
*/
/**
* \addtogroup global_fns Global/general functions
* @{
*/
#ifndef _MGRM_THREADS
/**
* \defgroup lite_fns MiniGUI-Processes specific functions
* @{
*/
#ifndef _MGRM_THREADS
/**
* \defgroup lite_listenfd_fns Listening a file descriptor
*
@@ -336,7 +334,7 @@ MG_EXPORT void GUIAPI MiniGUIPanic (int exitcode);
#define POLLERR 0x008
#endif
#endif
#endif /* WIN32 */
/**
* \fn BOOL GUIAPI RegisterListenFD (int fd, int type,\
@@ -1390,11 +1388,11 @@ MG_EXPORT int sock_read_t (int fd, void* buff, int count, unsigned int timeout);
/** @} end of lite_socket_fns */
/** @} end of lite_fns */
#endif /* _MGRM_PROCESSES */
#endif /* LITE_VERSION */
/** @} end of lite_fns */
#endif /* _MGRM_THREADS */
/**
* \defgroup init_fns Initialization and termination functions
@@ -1465,7 +1463,7 @@ MG_EXPORT void GUIAPI ExitGUISafely (int exitcode);
int minigui_entry (int args, const char* arg[]);
#else
#define main_entry main
#endif
#endif /* _USE_MINIGUIENTRY */
/**
* \def MiniGUIMain
@@ -1618,13 +1616,13 @@ MG_EXPORT void GUIAPI DesktopUpdateAllWindow (void);
/** @} end of init_fns */
#ifdef _MGHAVE_MOUSECALIBRATE
/**
* \defgroup mouse_calibrate Mouse calibration.
* @{
*/
#ifdef _MGHAVE_MOUSECALIBRATE
/**
* \fn BOOL GUIAPI SetMouseCalibrationParameters (const POINT* src_pts,\
const POINT* dst_pts)
@@ -1678,15 +1676,17 @@ MG_EXPORT BOOL GUIAPI SetMouseCalibrationParameters (const POINT* src_pts,
*/
MG_EXPORT void GUIAPI GetOriginalMousePosition (int* x, int* y);
/** @} end of mouse_calibrate */
#endif /* _MGHAVE_MOUSECALIBRATE */
/** @} end of mouse_calibrate */
#ifdef _MGMISC_ABOUTDLG
/**
* \defgroup about_dlg About MiniGUI dialog
* @{
*/
#ifdef _MGMISC_ABOUTDLG
#ifdef _MGRM_THREADS
/**
* \fn HWND GUIAPI OpenAboutDialog (void)
@@ -1703,8 +1703,9 @@ MG_EXPORT void GUIAPI GetOriginalMousePosition (int* x, int* y);
* _MGMISC_ABOUTDLG defined. For MiniGUI-Processes, you should
* call 'void GUIAPI OpenAboutDialog (HWND hHosting)' function instead.
*/
MG_EXPORT void GUIAPI OpenAboutDialog (void);
#else
MG_EXPORT void GUIAPI OpenAboutDialog (void);
#else /* _MGRM_THREADS */
/**
* \fn HWND GUIAPI OpenAboutDialog (HWND hHosting)
@@ -1724,11 +1725,13 @@ MG_EXPORT void GUIAPI OpenAboutDialog (void);
* call 'void GUIAPI OpenAboutDialog (void)' function instead.
*/
MG_EXPORT HWND GUIAPI OpenAboutDialog (HWND hHosting);
#endif /* _MGRM_THREADS */
#endif /* _MGMISC_ABOUTDLG */
/** @} end of about_dlg */
#endif /* _MGMISC_ABOUTDLG */
/**
* \defgroup etc_fns Configuration file operations
*
@@ -1871,7 +1874,7 @@ typedef struct _ETC_S
*/
extern MG_EXPORT char ETCFILEPATH [];
#endif /* _MGINCORE_RES */
#endif /* !_MGINCORE_RES */
/**
* \fn int GUIAPI GetValueFromEtcFile (const char* pEtcFile,\
@@ -2248,7 +2251,7 @@ static inline int GetMgEtcValue(const char* pSection,
#ifndef _MGINCORE_RES
if (!hMgEtc)
return GetValueFromEtcFile (ETCFILEPATH, pSection, pKey, pValue, iLen);
#endif
#endif /* !_MGINCORE_RES */
return GetValueFromEtc (hMgEtc, pSection, pKey, pValue, iLen);
}
@@ -2268,7 +2271,7 @@ static inline int GetMgEtcIntValue (const char *pSection,
#ifndef _MGINCORE_RES
if (!hMgEtc)
return GetIntValueFromEtcFile (ETCFILEPATH, pSection, pKey, value);
#endif
#endif /* !_MGINCORE_RES */
return GetIntValueFromEtc (hMgEtc, pSection, pKey, value);
}
@@ -3594,8 +3597,8 @@ MG_EXPORT char * strtrimall (char* src);
*/
/**
* mg_slice_alloc:
* @block_size: the number of bytes to allocate
* \fn void *mg_slice_alloc(size_t block_size)
* \brief Allocate a slice memory.
*
* Allocates a block of memory from the slice allocator.
* The block address handed out can be expected to be aligned
@@ -3607,82 +3610,91 @@ MG_EXPORT char * strtrimall (char* src);
* be changed with the [`MG_SLICE=always-malloc`][MG_SLICE]
* environment variable.
*
* Returns: a pointer to the allocated memory block, which will be %NULL if and
* only if @mem_size is 0
* \param block_size The number of bytes to allocate.
*
* \return A pointer to the allocated memory block, which will be NULL
* if and only if \a mem_size is 0.
*
* Since: 4.0.0
*/
MG_EXPORT void *mg_slice_alloc(size_t block_size);
/**
* mg_slice_alloc0:
* @block_size: the number of bytes to allocate
* \fn void *mg_slice_alloc0(size_t block_size)
* \brief Allocate a slice memory and initialize the memory to zero.
*
* Allocates a block of memory via mg_slice_alloc() and initializes
* the returned memory to 0. Note that the underlying slice allocation
* mechanism can be changed with the [`MG_SLICE=always-malloc`][MG_SLICE]
* environment variable.
*
* Returns: a pointer to the allocated block, which will be %NULL if and only
* if @mem_size is 0
* \param block_size The number of bytes to allocate.
*
* \return A pointer to the allocated block, which will be NULL
* if and only if \a mem_size is 0.
*
* Since: 4.0.0
*/
MG_EXPORT void *mg_slice_alloc0(size_t block_size);
/**
* mg_slice_copy:
* @block_size: the number of bytes to allocate
* @mem_block: the memory to copy
* \fn void *mg_slice_copy(size_t block_size, const void *mem_block)
* \brief Allocate and copy a slice.
*
* Allocates a block of memory from the slice allocator
* and copies @block_size bytes into it from @mem_block.
* and copies \a block_size bytes into it from \a mem_block.
*
* @mem_block must be non-%NULL if @block_size is non-zero.
* \param block_size The number of bytes to allocate.
* \param mem_block The memory to copy.
*
* Returns: a pointer to the allocated memory block, which will be %NULL if and
* only if @mem_size is 0
* \return A pointer to the allocated memory block, which will be NULL
* if and only if \a mem_size is 0.
*
* \note \a mem_block must be non-NULL if \a block_size is non-zero.
*
* Since: 4.0.0
*/
MG_EXPORT void *mg_slice_copy(size_t block_size, const void *mem_block);
/**
* mg_slice_free:
* @block_size: the size of the block
* @mem_block: a pointer to the block to free
* \fn void mg_slice_free(size_t block_size, void *mem_block)
* \brief Free a block of memory.
*
* Frees a block of memory.
*
* The memory must have been allocated via mg_slice_alloc() or
* mg_slice_alloc0() and the @block_size has to match the size
* This function frees a block of memory. The memory must have been
* allocated via \a mg_slice_alloc or
* \a mg_slice_alloc0 and the \a block_size has to match the size
* specified upon allocation. Note that the exact release behaviour
* can be changed with the [`MG_DEBUG=gc-friendly`][MG_DEBUG] environment
* variable, also see [`MG_SLICE`][MG_SLICE] for related debugging options.
*
* If @mem_block is %NULL, this function does nothing.
* If \a mem_block is NULL, this function does nothing.
*
* \param block_size The size of the block.
* \param mem_block A pointer to the block to free.
*
* Since: 4.0.0
*/
MG_EXPORT void mg_slice_free(size_t block_size, void *mem_block);
/**
* mg_slice_free_chain_with_offset:
* @block_size: the size of the blocks
* @mem_chain: a pointer to the first block of the chain
* @next_offset: the offset of the @next field in the blocks
*
* Frees a linked list of memory blocks of structure type @type.
* \fn void mg_slice_free_chain_with_offset(size_t block_size,
void *mem_chain, size_t next_offset)
* \brief Free a linked list of memory blocks.
*
* The memory blocks must be equal-sized, allocated via
* mg_slice_alloc() or mg_slice_alloc0() and linked together by a
* @next pointer (similar to #GSList). The offset of the @next
* field in each block is passed as third argument.
* next pointer. The offset of the next field in each block is passed
* as the third argument \a next_offset.
*
* Note that the exact release behaviour can be changed with the
* [`MG_DEBUG=gc-friendly`][MG_DEBUG] environment variable, also see
* [`MG_SLICE`][MG_SLICE] for related debugging options.
*
* If @mem_chain is %NULL, this function does nothing.
* If \a mem_chain is NULL, this function does nothing.
*
* \param block_size The size of the blocks.
* \param mem_chain A pointer to the first block of the chain.
* \param next_offset The offset of the next field in the blocks.
*
* Since: 4.0.0
*/
@@ -3690,47 +3702,52 @@ MG_EXPORT void mg_slice_free_chain_with_offset(size_t block_size,
void *mem_chain, size_t next_offset);
/**
* mg_slice_new:
* @type: the type to allocate, typically a structure name
* \def mg_slice_new(type)
* \brief The macro to allocate a slice memory for a structure.
*
* A convenience macro to allocate a block of memory from the
* This is a convenience macro to allocate a block of memory from the
* slice allocator.
*
* It calls mg_slice_alloc() with `sizeof (@type)` and casts the
* It calls mg_slice_alloc() with `sizeof(type)` and casts the
* returned pointer to a pointer of the given type, avoiding a type
* cast in the source code. Note that the underlying slice allocation
* mechanism can be changed with the [`MG_SLICE=always-malloc`][MG_SLICE]
* environment variable.
*
* This can never return %NULL as the minimum allocation size from
* `sizeof (@type)` is 1 byte.
* This can never return NULL as the minimum allocation size from
* `sizeof(type)` is 1 byte.
*
* Returns: (not nullable): a pointer to the allocated block, cast to a pointer
* to @type
* \param type the type to allocate, typically a structure name.
*
* \return A pointer to the allocated block, cast to a pointer
* to \a type.
*
* Since: 4.0.0
*/
#define mg_slice_new(type) ((type*)mg_slice_alloc(sizeof (type)))
/**
* mg_slice_new0:
* @type: the type to allocate, typically a structure name
* \def mg_slice_new0(type)
* \brief The macro to allocate a zero'd slice memory for a structure.
*
* A convenience macro to allocate a block of memory from the
* This is a convenience macro to allocate a block of memory from the
* slice allocator and set the memory to 0.
*
* It calls mg_slice_alloc0() with `sizeof (@type)`
* It calls mg_slice_alloc0() with `sizeof(type)`
* and casts the returned pointer to a pointer of the given type,
* avoiding a type cast in the source code.
*
* Note that the underlying slice allocation mechanism can
* be changed with the [`MG_SLICE=always-malloc`][MG_SLICE]
* environment variable.
*
* This can never return %NULL as the minimum allocation size from
* `sizeof (@type)` is 1 byte.
* This can never return NULL as the minimum allocation size from
* `sizeof(type)` is 1 byte.
*
* Returns: (not nullable): a pointer to the allocated block, cast to a pointer
* to @type
* \param type The type to allocate, typically a structure name.
*
* \return A pointer to the allocated block, cast to a pointer
* to \a type.
*
* Since: 4.0.0
*/
@@ -3748,24 +3765,25 @@ MG_EXPORT void mg_slice_free_chain_with_offset(size_t block_size,
*/
/**
* mg_slice_dup:
* @type: the type to duplicate, typically a structure name
* @mem: (not nullable): the memory to copy into the allocated block
* \def mg_slice_dup(type, mem)
* \brief Duplicate a structure.
*
* A convenience macro to duplicate a block of memory using
* This is a convenience macro to duplicate a block of memory using
* the slice allocator.
*
* It calls mg_slice_copy() with `sizeof (@type)`
* It calls mg_slice_copy() with `sizeof(type)`
* and casts the returned pointer to a pointer of the given type,
* avoiding a type cast in the source code.
* Note that the underlying slice allocation mechanism can
* be changed with the [`MG_SLICE=always-malloc`][MG_SLICE]
* environment variable.
*
* This can never return %NULL.
* This can never return NULL.
*
* Returns: (not nullable): a pointer to the allocated block, cast to a pointer
* to @type
* \param type The type to duplicate, typically a structure name.
* \param mem The memory to copy into the allocated block.
*
* \return A pointer to the allocated block, cast to a pointer to \a type.
*
* Since: 4.0.0
*/
@@ -3774,20 +3792,24 @@ MG_EXPORT void mg_slice_free_chain_with_offset(size_t block_size,
: ((void) ((type*) 0 == (mem)), (type*) 0))
/**
* mg_slice_delete:
* @type: the type of the block to free, typically a structure name
* @mem: a pointer to the block to free
* \def mg_slice_delete(type, mem)
* \brief Free a block of memory.
*
* A convenience macro to free a block of memory that has
* This is a convenience macro to free a block of memory that has
* been allocated from the slice allocator.
*
* It calls mg_slice_free() using `sizeof (type)`
* as the block size.
* It calls mg_slice_free() using `sizeof(type)` as the block size.
*
* Note that the exact release behaviour can be changed with the
* [`MG_DEBUG=gc-friendly`][MG_DEBUG] environment variable, also see
* [`MG_SLICE`][MG_SLICE] for related debugging options.
*
* If @mem is %NULL, this macro does nothing.
* If \a mem is NULL, this macro does nothing.
*
* \param type The type of the block to free, typically a structure name.
* \param mem A pointer to the block to free.
*
* \return None.
*
* Since: 4.0.0
*/
@@ -3798,21 +3820,26 @@ MG_EXPORT void mg_slice_free_chain_with_offset(size_t block_size,
} while(0)
/**
* mg_slice_delete_chain:
* @type: the type of the @mem_chain blocks
* @mem_chain: a pointer to the first block of the chain
* @next: the field name of the next pointer in @type
* \def mg_slice_delete_chain(type, mem_chain, next)
* \brief Free a linked list of memory blocks.
*
* This function frees a linked list of memory blocks of
* structure type \a type.
*
* Frees a linked list of memory blocks of structure type @type.
* The memory blocks must be equal-sized, allocated via
* mg_slice_alloc() or mg_slice_alloc0() and linked together by
* a @next pointer (similar to #GSList). The name of the
* @next field in @type is passed as third argument.
* a \a next pointer. The name of the
* \a next field in \a type is passed as third argument.
*
* Note that the exact release behaviour can be changed with the
* [`MG_DEBUG=gc-friendly`][MG_DEBUG] environment variable, also see
* [`MG_SLICE`][MG_SLICE] for related debugging options.
*
* If @mem_chain is %NULL, this function does nothing.
* If \a mem_chain is NULL, this function does nothing.
*
* \param type The type of the \a mem_chain blocks.
* \param mem_chain A pointer to the first block of the chain.
* \param next The field name of the next pointer in \a type.
*
* Since: 4.0.0
*/