functions.h

用STL的方式封装了WindowsAPI、COM调用、ACE、ATL、MFC、WTL等多种组件

/* /////////////////////////////////////////////////////////////////////////
 * File:        winstl/control_panel/functions.h
 *
 * Purpose:     Control Panel functions.
 *
 * Created:     1st April 2006
 * Updated:     18th June 2006
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2006, Matthew Wilson and Synesis Software
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
 *   any contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * ////////////////////////////////////////////////////////////////////// */


/** \file winstl/control_panel/functions.h
 *
 * \brief [C, C++] Control Panel functions.
 *  (\ref group__library__windows_control_panel "Windows Control Panel"
 *  library.)
 */

#ifndef WINSTL_INCL_WINSTL_CONTROL_PANEL_H_FUNCTIONS
#define WINSTL_INCL_WINSTL_CONTROL_PANEL_H_FUNCTIONS

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define WINSTL_VER_WINSTL_CONTROL_PANEL_H_FUNCTIONS_MAJOR      1
# define WINSTL_VER_WINSTL_CONTROL_PANEL_H_FUNCTIONS_MINOR      0
# define WINSTL_VER_WINSTL_CONTROL_PANEL_H_FUNCTIONS_REVISION   4
# define WINSTL_VER_WINSTL_CONTROL_PANEL_H_FUNCTIONS_EDIT       6
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Compatibility
 */

/*
[Incompatibilies-start]
STLSOFT_COMPILER_IS_GCC:     __GNUC__ < 3 || (__GNUC__ == 3 && __GNUC_MINOR__ < 3)
[Incompatibilies-end]
 */

/* /////////////////////////////////////////////////////////////////////////
 * Includes
 */

#ifndef WINSTL_INCL_WINSTL_H_WINSTL
# include <winstl/winstl.h>
#endif /* !WINSTL_INCL_WINSTL_H_WINSTL */
#include <cpl.h>

/* /////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#ifndef _WINSTL_NO_NAMESPACE
# if defined(_STLSOFT_NO_NAMESPACE) || \
     defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
/* There is no stlsoft namespace, so must define ::winstl */
namespace winstl
{
# else
/* Define stlsoft::winstl_project */

namespace stlsoft
{

namespace winstl_project
{

# endif /* _STLSOFT_NO_NAMESPACE */
#endif /* !_WINSTL_NO_NAMESPACE */

/* /////////////////////////////////////////////////////////////////////////
 * Typedefs
 */

/** \brief Function pointer representing the entry point provide by all
 *   control panel applet modules.
 */
typedef LONG (APIENTRY *control_panel_entry_t)(HWND , UINT , LONG , LONG );

/* /////////////////////////////////////////////////////////////////////////
 * C functions
 */

/** \brief [C, C++] Initialises a control panel applet module.
 *
 * \ingroup group__library__windows_control_panel
 */
STLSOFT_INLINE BOOL winstl__control_panel_init(control_panel_entry_t entry, HWND hwnd)
{
    WINSTL_ASSERT(NULL != entry);

    return (*entry)(hwnd, CPL_INIT, 0, 0);
}

/** \brief [C, C++] Uninitialises a control panel applet module.
 *
 * \ingroup group__library__windows_control_panel
 *
 */
STLSOFT_INLINE void winstl__control_panel_uninit(control_panel_entry_t entry, HWND hwnd)
{
    WINSTL_ASSERT(NULL != entry);

    stlsoft_static_cast(void, (*entry)(hwnd, CPL_EXIT, 0, 0));
}

/** \brief [C, C++] Retrieves the number of control panel applets within a control panel applet module.
 *
 * \ingroup group__library__windows_control_panel
 *
 */
STLSOFT_INLINE ss_size_t winstl__control_panel_get_count(control_panel_entry_t entry, HWND hwnd)
{
    WINSTL_ASSERT(NULL != entry);

    return stlsoft_static_cast(ss_size_t, (*entry)(hwnd, CPL_GETCOUNT, 0, 0));
}

/** \brief [C, C++] Issues an inquiry control (CPL_INQUIRE) to a control panel applet.
 *
 * \ingroup group__library__windows_control_panel
 *
 */
STLSOFT_INLINE void winstl__control_panel_inquire(control_panel_entry_t entry, HWND hwnd, ss_size_t index, LPCPLINFO info)
{
    WINSTL_ASSERT(NULL != entry);
    WINSTL_ASSERT(NULL != info);
    WINSTL_ASSERT(index < winstl__control_panel_get_count(entry, hwnd));

    stlsoft_static_cast(void, (*entry)(hwnd, CPL_INQUIRE, stlsoft_static_cast(LONG, index), stlsoft_reinterpret_cast(LONG, info)));
}

/** \brief [C, C++] Issues a "new" inquiry control (CPL_NEWINQUIRE) to a control panel applet.
 *
 * \ingroup group__library__windows_control_panel
 *
 */
STLSOFT_INLINE void winstl__control_panel_newinquire(control_panel_entry_t entry, HWND hwnd, ss_size_t index, LPNEWCPLINFO info)
{
    /* Some applets don't handle sizeof(NEWCPLINFOA), so we try with Unicode first. */
    union
    {
        NEWCPLINFOA infoa_;
        NEWCPLINFOW infow_;
    }       u;

    WINSTL_ASSERT(NULL != entry);
    WINSTL_ASSERT(NULL != info);
    WINSTL_ASSERT(sizeof(NEWCPLINFOA) != info->dwSize || sizeof(NEWCPLINFOW) != info->dwSize);
    WINSTL_ASSERT(index < winstl__control_panel_get_count(entry, hwnd));

    u.infoa_.dwFlags        =   0;
    u.infoa_.dwHelpContext  =   0;
    u.infoa_.lData          =   0;
    u.infoa_.hIcon          =   NULL;
    u.infoa_.szName[0]      =   L'\0';
    u.infoa_.szInfo[0]      =   L'\0';
    u.infoa_.szHelpFile[0]  =   L'\0';
    u.infow_.szName[0]      =   L'\0';
    u.infow_.szInfo[0]      =   L'\0';
    u.infow_.szHelpFile[0]  =   L'\0';

    if(sizeof(NEWCPLINFOW) == info->dwSize)
    {
        /* Try Unicode first. */
        LPNEWCPLINFOW   infow   =   stlsoft_reinterpret_cast(LPNEWCPLINFOW, info);

        u.infow_.dwSize = sizeof(NEWCPLINFOW);

        stlsoft_static_cast(void, (*entry)(hwnd, CPL_NEWINQUIRE, stlsoft_static_cast(LONG, index), stlsoft_reinterpret_cast(LONG, &u.infow_)));

        if( u.infow_.dwSize == sizeof(NEWCPLINFOW) &&
            L'\0' != u.infow_.szName[0])
        {
            *infow = u.infow_;
        }
        else
        {
            /* Unicode failed, so try ANSI. */
            u.infoa_.dwSize = sizeof(NEWCPLINFOA);

            stlsoft_static_cast(void, (*entry)(hwnd, CPL_NEWINQUIRE, stlsoft_static_cast(LONG, index), stlsoft_reinterpret_cast(LONG, &u.infoa_)));

            STLSOFT_NS_GLOBAL(MultiByteToWideChar)(0, 0, u.infoa_.szName, -1, infow->szName, STLSOFT_NUM_ELEMENTS(u.infow_.szName));
            STLSOFT_NS_GLOBAL(MultiByteToWideChar)(0, 0, u.infoa_.szInfo, -1, infow->szInfo, STLSOFT_NUM_ELEMENTS(u.infow_.szInfo));
            STLSOFT_NS_GLOBAL(MultiByteToWideChar)(0, 0, u.infoa_.szHelpFile, -1, infow->szHelpFile, STLSOFT_NUM_ELEMENTS(u.infow_.szHelpFile));
        }
    }
    else
    {
        /* Try ANSI first. */
        LPNEWCPLINFOA   infoa   =   stlsoft_reinterpret_cast(LPNEWCPLINFOA, info);

        u.infoa_.dwSize = sizeof(NEWCPLINFOA);

        stlsoft_static_cast(void, (*entry)(hwnd, CPL_NEWINQUIRE, stlsoft_static_cast(LONG, index), stlsoft_reinterpret_cast(LONG, &u.infoa_)));

        if( u.infoa_.dwSize == sizeof(NEWCPLINFOA) &&