//
// validate.h
//
// Copyright (c) 1997-1999 Microsoft Corporation. All rights reserved.
//
// Parameter validation macros
//
// Summary:
//
// V_INAME(interfacename)                - Set the interface name for error display
// V_STRUCTPTR_READ(ptr,type)            - A dwSize struct which we will read
// V_STRUCTPTR_WRITE(ptr,type)           - A dwSize struct which we will read/write
// V_PTR_READ(ptr,type)                  - A typed ptr w/o a dwSize which we will read
// V_PTR_WRITE(ptr,type)                 - A typed ptr w/o a dwSize which we will read/write
// V_PTR_WRITE_OPT(ptr,type)             - An optional typed ptr w/o a dwSize which we will read/write
// V_BUFPTR_READ(ptr,size)               - A variable-size buffer that we will read
// V_BUFPTR_READ_OPT(ptr,size)			 - An optional variable-size buffer that we will read
// V_BUFPTR_WRITE(ptr,size)              - A variable-size buffer that we will read/write
// V_BUFPTR_WRITE_OPT(ptr,size)          - An optional variable-size buffer that we will read/write
// V_PTRPTR_WRITE(ptrptr)                - A pointer to a pointer to write to
// V_PTRPTR_WRITE_OPT(ptrptr)            - A pointer to a pointer to write to that is optional
// V_PUNKOUTER(punk)                     - A pointer to a controlling unknown, aggregation supported
// V_PUNKOUTER_NOADD(punk)               - A pointer to a controlling unknown, aggregation not supported
// V_INTERFACE(ptr)                      - A pointer to a COM interface
// V_INTERFACE_OPT(ptr)                  - An optional pointer to a COM interface
// V_REFGUID(ref)                        - A reference to a GUID (type REFGUID)
// V_HWND(hwnd)							 - A window handle
// V_HWNDOPT(hwnd)						 - An optional window handle
//
// For handling different versions of structures:
// 
// V_STRUCTPTR_READ_VER(ptr,ver)         - Begin a struct version block for read access
//                                         At the end, 'ver' will contain the 
//                                         discovered version of the struct
// V_STRUCTPTR_READ_VER_CASE(base,ver)   - Test struct against version ver of
//                                         type 'base'. 
// V_STRUCTPTR_READ_VER_END(base,ptr)    - End a struct version block
//
// V_STRUCTPTR_WRITE_VER(ptr,ver)        - Struct version block for write access
// V_STRUCTPTR_WRITE_VER_CASE(base,ver)
// V_STRUCTPTR_WRITE_VER_END(base,ptr)
//
// The struct version block expects type names of a base type followed by a 
// numeric version, such as
//
// typedef struct { } FOO7;
// typedef struct { } FOO8;
//
// In the header FOO and LPFOO are conditionally typedef'd based on a version
// #define. The DLL will be compiled with the latest version number and hence
// the largest version of the struct.
//
// Since Windows headers are compiled by default with 8-byte alignment, adding
// one DWORD may not cause the size of the structure to change. If this happens
// you will get a 'case label already used' error on one of the VER_CASE macros.
// If this happens, you can get around it by adding a dwReserved field to the 
// end of the struct to force the padding.
//
// 'optional' means the pointer is allowed to be NULL by the interface specification.
//
// Sample usage:
//
// int IDirectMusic::SetFooBarInterface(
//     LPDMUS_REQUESTED_CAPS    pCaps,          // Caps w/ dwSize (read-only)
//     LPVOID                   pBuffer,        // Buffer we will fill in
//     DWORD                    cbSize,         // Size of the buffer
//     PDIRECTMUSICBAR          pBar)           // Callback interface for bar on this buffer
// {
//     V_INTERFACE(IDirectMusic::SetFooBarInterface);
//     V_BUFPTR_WRITE(pBuffer, cbSize);
//     V_INTERFACE(pBar);
//     DWORD dwCapsVer;                         // Must be a DWORD!!!
//
//     V_STRUCTPTR_READ_VER(pCaps, dwCapsVer);
//     V_STRUCTPTR_READ_VER_CASE(DMUS_REQUESTED_CAPS, 7);
//     V_STRUCTPTR_READ_VER_CASE(DMUS_REQUESTED_CAPS, 8);
//     V_STRUCTPTR_READ_VER_END_(DMUS_REQUESTED_CAPS, pCaps);
//
//     // At this point, if we are still in the function we have a valid pCaps
//     // pointer and dwCapsVer is either 7 or 8, indicating the version of
//     // the struct passed in.
//
//     ...
// }
//
#ifndef _VALIDATE_H_
#define _VALIDATE_H_


#ifdef DBG
#include <stddef.h>

#include "debug.h"

// To turn on DebugBreak on parameter error, use the following or -DRIP_BREAK in the build:
//
//#define RIP_BREAK 1

#ifdef RIP_BREAK
#define _RIP_BREAK DebugBreak();
#else
#define _RIP_BREAK 
#endif

#define V_INAME(x) \
    static const char __szValidateInterfaceName[] = #x;                       

#define RIP_E_POINTER(ptr) \
{   Trace(-1, "%s: Invalid pointer " #ptr "\n", __szValidateInterfaceName); \
    _RIP_BREAK \
    return E_POINTER; }

#define RIP_E_INVALIDARG(ptr) \
{   Trace(-1, "%s: Invalid argument " #ptr "\n", __szValidateInterfaceName); \
    _RIP_BREAK \
    return E_INVALIDARG; }

#define RIP_E_HANDLE(h) \
{	Trace(-1, "%s: Invalid handle " #h "\n", __szValidateInterfaceName); \
    _RIP_BREAK \
	return E_HANDLE; }
    
#define RIP_W_INVALIDSIZE(ptr) \
{   Trace(-1, "%s: " #ptr "->dwSize matches no known structure size. Defaulting to oldest structure.\n", \
    __szValidateInterfaceName); \
    _RIP_BREAK \
    }
    
#define RIP_E_INVALIDSIZE(ptr) \
{   Trace(-1, "%s: " #ptr "->dwSize is too small\n", __szValidateInterfaceName); \
    _RIP_BREAK \
    return E_INVALIDARG; }
    
#define RIP_E_BLOCKVSDWSIZE(ptr) \
{   Trace(-1, "%s: " #ptr " does not point to as much memory as " #ptr "->dwSize indicates\n", \
    __szValidateInterfaceName); \
    _RIP_BREAK \
    return E_INVALIDARG; }    

// NOTE: The DebugBreak() not in #ifdef is intentional - this is something that
// must be fixed in our code, not an app-generated error.
//
#define V_ASSERT(exp) \
{   if (!(exp)) { \
        Trace(-1, "%s@%s: %s\n", __FILE__, __LINE__, #exp); \
        DebugBreak(); }}

#else

#define V_INAME(x)
#define RIP_E_POINTER(ptr)          { return E_POINTER; }
#define RIP_E_INVALIDARG(ptr)       { return E_INVALIDARG; }
#define RIP_E_HANDLE(h)	            { return E_HANDLE; }
#define RIP_E_BLOCKVSDWSIZE(ptr)    { return E_INVALIDARG; }
#define RIP_W_INVALIDSIZE(ptr)
#define RIP_E_INVALIDSIZE(ptr)      { return E_INVALIDARG; }
#define V_ASSERT(exp)

#endif          // DBG

// A passed struct we will only read from or may write to. Must be a struct
// with a dwSize.
//
// int foo(CFoo *pFoo)
// ...
// V_STRUCTPTR_READ(pFoo, CFoo);
// V_STRUCTPTR_WRITE(pFoo, CFoo);
//
// Use _PTR_ variants for structs w/o a dwSize
//
#define V_STRUCTPTR_READ(ptr,type) \
{   V_ASSERT(offsetof(type, dwSize) == 0); \
    if (IsBadReadPtr(ptr, sizeof(DWORD)))               RIP_E_BLOCKVSDWSIZE(ptr); \
	if (ptr->dwSize < sizeof(type))						RIP_E_INVALIDSIZE(ptr); \
    if (IsBadReadPtr(ptr, (ptr)->dwSize))               RIP_E_BLOCKVSDWSIZE(ptr); }

#define V_STRUCTPTR_WRITE(ptr,type) \
{   V_ASSERT(offsetof(type, dwSize) == 0); \
    if (IsBadReadPtr(ptr, sizeof(DWORD)))               RIP_E_BLOCKVSDWSIZE(ptr); \
	if (ptr->dwSize < sizeof(type))						RIP_E_INVALIDSIZE(ptr); \
    if (IsBadWritePtr(ptr, (ptr)->dwSize))              RIP_E_BLOCKVSDWSIZE(ptr); }

#define V_PTR_READ(ptr,type) \
{ if (IsBadReadPtr(ptr, sizeof(type)))                  RIP_E_POINTER(ptr); }

#define V_PTR_WRITE(ptr,type) \
{ if (IsBadWritePtr(ptr, sizeof(type)))                 RIP_E_POINTER(ptr); }

#define V_PTR_WRITE_OPT(ptr,type) \
{ if (ptr) if (IsBadWritePtr(ptr, sizeof(type)))        RIP_E_POINTER(ptr); }

// A buffer pointer with separate length (not defined by the pointer type) we will only
// read from or may write to.
//
// int foo(LPVOID *pBuffer, DWORD cbBuffer)
// ...
// V_BUFPTR_READ(pBuffer, cbBuffer);
// V_BUFPTR_WRITE(pBuffer, cbBuffer);
//
#define V_BUFPTR_READ(ptr,len) \
{   if (IsBadReadPtr(ptr, len))                         RIP_E_POINTER(ptr); }

#define V_BUFPTR_READ_OPT(ptr,len) \
{	if (ptr) V_BUFPTR_READ(ptr,len); }

#define V_BUFPTR_WRITE(ptr,len) \
{   if (IsBadWritePtr(ptr, len))                        RIP_E_POINTER(ptr); }

#define V_BUFPTR_WRITE_OPT(ptr,len) \
{	if (ptr) V_BUFPTR_WRITE(ptr,len); }

// A pointer to a pointer (such as a pointer to an interface pointer) to return
//
// int foo(IReturnMe **ppRet)
// ...
// V_PTRPTR_WRITE(ppRet);
// V_PTRPTR_WRITE_OPT(ppRet);
//
#define V_PTRPTR_WRITE(ptr) \
{   if (IsBadWritePtr(ptr, sizeof(void*)))              RIP_E_POINTER(ptr); }

#define V_PTRPTR_WRITE_OPT(ptr) \
{   if (ptr) if (IsBadWritePtr(ptr, sizeof(void*)))     RIP_E_POINTER(ptr); }

// A pointer to a controlling unknown
//
#define V_PUNKOUTER(punk) \
{   if (punk && IsBadCodePtr(punk))                     RIP_E_POINTER(ptr); }

// A pointer to a controlling unknown for which we don't support aggregation
//
#define V_PUNKOUTER_NOAGG(punk) \
{   if (punk && IsBadReadPtr(punk, sizeof(IUnknown)))   RIP_E_POINTER(ptr); \
    if (punk) return CLASS_E_NOAGGREGATION; }

// Validate an incoming interface pointer. 
//
struct _V_GENERIC_INTERFACE
{
    FARPROC *(__vptr[1]);
};

#define V_INTERFACE(ptr) \
{   if (IsBadReadPtr(ptr, sizeof(_V_GENERIC_INTERFACE)))                              RIP_E_POINTER(ptr); \
    if (IsBadReadPtr(*reinterpret_cast<_V_GENERIC_INTERFACE*>(ptr)->__vptr, sizeof(FARPROC))) \
                                                                                      RIP_E_POINTER(ptr); \
    if (IsBadCodePtr(*(reinterpret_cast<_V_GENERIC_INTERFACE*>(ptr)->__vptr)[0]))     RIP_E_POINTER(ptr); }

#define V_INTERFACE_OPT(ptr) \
{   if (ptr) V_INTERFACE(ptr); }

// Validation for a reference to a GUID, which we only ever read. 
//
#define V_REFGUID(ref) \
{   if (IsBadReadPtr((void*)&ref, sizeof(GUID)))        RIP_E_POINTER((void*)&ref); }

// Validation for a window handle
//
#define V_HWND(h) \
{	if (!IsWindow(h))									RIP_E_HANDLE(h); }	

#define V_HWND_OPT(h) \
{	if (h) if (!IsWindow(h))							RIP_E_HANDLE(h); }	

// Validation for multiple sized structs based on version
//
#define V_STRUCTPTR_READ_VER(ptr,ver) \
{   ver = 7; DWORD *pdw = &ver;  \
    if (IsBadReadPtr(ptr, sizeof(DWORD)))               RIP_E_BLOCKVSDWSIZE(ptr); \
    if (IsBadReadPtr(ptr, (ptr)->dwSize))               RIP_E_BLOCKVSDWSIZE(ptr); \
    switch ((ptr)->dwSize) {
    
#define V_STRUCTPTR_READ_VER_CASE(basetype,ver) \
    case sizeof(basetype##ver) : \
    V_ASSERT(offsetof(basetype##ver, dwSize) == 0); \
    *pdw = ver; break;
    
#define V_STRUCTPTR_READ_VER_END(basetype,ptr) \
    default : if ((ptr)->dwSize > sizeof(basetype##7)) \
    { RIP_W_INVALIDSIZE(ptr); } else \
    RIP_E_INVALIDSIZE(ptr); }}


#define V_STRUCTPTR_WRITE_VER(ptr,ver) \
{   ver = 7; DWORD *pdw = &ver;  \
    if (IsBadReadPtr(ptr, sizeof(DWORD)))               RIP_E_BLOCKVSDWSIZE(ptr); \
    if (IsBadWritePtr(ptr, (ptr)->dwSize))              RIP_E_BLOCKVSDWSIZE(ptr); \
    switch ((ptr)->dwSize) {
    
#define V_STRUCTPTR_WRITE_VER_CASE(basetype,ver) \
    case sizeof(basetype##ver) : \
        V_ASSERT(offsetof(basetype##ver, dwSize) == 0); \
        *pdw = ver; break;
    
#define V_STRUCTPTR_WRITE_VER_END(basetype,ptr) \
    default : if ((ptr)->dwSize > sizeof(basetype##7)) \
    { RIP_W_INVALIDSIZE(ptr); } else \
    RIP_E_INVALIDSIZE(ptr); }}



#endif          // _VALIDATE_H_