xHarbour Reference Documentation > Class Reference (textmode)

C Structure class

Abstract class for C structure support.

Description

xHarbour supports C structures as they are required by many external API functions, such as the Windows API, or Third Party libraries. The C Structure class is an abstract class serving as super class for all structures declared with the typedef struct declaration. Instance variables and methods of this class are available in all declared structures.

On the PRG level, a structure is represented by an object whose instance variables hold the values of structure members. On the C level it is a contiguous binary character string holding the structure members. This character string is maintained by a structure object in an internal buffer which can be retrieved with the :value() method, or changed with the :buffer() method.

In contrast to other classes, C structures are not instantiated with a :new() or :init() method, but with the structure creation statement (struct).

Predefined structures in xHarbour

The #include file Winapi.ch contains a large number of predefined structures that are required by Windows API functions. If a Windows API function is called on the PRG level via DllCall() that requires a structure as parameter, the corresponding structure declaration can be done by simply including the Winapi.ch file. The following table lists the structures that are available when WinApi.ch is included:

Structures for Windows API functions

Declared	Structure	Names
CHOOSEFONT	NMHEADER	RECT
CLIENTCREATESTRUCT	NMPGCALCSIZE	SCROLLBARINFO
COLORSCHEME	NMPGSCROLL	SCROLLINFO
CREATESTRUCT	NMREBARCHEVRON	SIZE
DLGITEMTEMPLATE	NMREBAR	TBADDBITMAP
DLGTEMPLATEEX	NMTBCUSTOMDRAW	TBBUTTON
DLGTEMPLATE	NMTBHOTITEM	TBBUTTONINFOA
DRAWITEMSTRUCT	NMTOOLBARA	TCITEMA
HDITEM	NMTREEVIEWA	TEXTMETRIC
ICONINFO	NMTVCUSTOMDRAW	TOOLINFOA
LITEM	NMTVGETINFOTIP	TOOLTIPTEXT
LOGFONT	NMTVKEYDOWN	TRACKMOUSEEVENT
LVCOLUMNA	NONCLIENTMETRICS	TVHITTESTINFO
LVITEMA	OPENFILENAME	TVINSERTSTRUCT
MDINEXTMENU	OSVERSIONINFO	TVITEMEX
MEASUREITEMSTRUCT	OSVERSIONINFOEX	TVITEM
MENUINFO	PAINTSTRUCT	WINDOWPLACEMENT
MENUITEMINFO	POINTS	WINDOWPOS
MSG	POINT	WNDCLASSEX
NCCALCSIZE_PARAMS	RBHITTESTINFO	WNDCLASS
NMCUSTOMDRAW	REBARBANDINFOA
NMHDR	REBARINFO

Instance variables

:aCMembers

Array holding the structure member names.

:aCTypes

Array holding the data types of structure members.

:nAlign

Byte alignment of structure members

Methods

:array() --> aMemberValues

Fills an array with all structure member values.

:buffer( <cBuffer>, [<lRecurse>] ) --> self

Assigns a binary character string to the internal buffer.

:deValue( [<lRecurse>] ) --> self

Re-loads binary structure data from memory.

:getPointer() --> pStructure

Retrieves the pointer to the internal binary buffer.

:pointer( <pStructure>, [<lRecurse>] ) --> self

Changes the pointer to the internal binary buffer.

:reset() --> self

Voids the values of all structure members.

:sizeOf() --> nStructureSize

Determines the size of a structure in bytes.

:value() --> cBinaryStructure

Retrieves the internal binary buffer of a structure object

Info

See also:	DllCall(), HB_Pointer2String(), HB_String2Pointer(), pragma pack(), (struct), typedef struct
Category:	C Structure support , xHarbour extensions
Header:	cstruct.ch, winapi.ch, wintypes.ch
Source:	rtl\cstruct.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example outlines the steps necessary for calling a
// Windows API function which requires a structure as parameter.

   #include "CStruct.ch"         // required for "typedef struct"
   #include "Wintypes.ch"        // required Windows C data types

   pragma pack(4)                // all Windows API structures
                                 // are 4 byte aligned

                                 // structure declaration taken via
                                 // copy&paste from Windows SDK
   typedef struct _OSVERSIONINFOEX { ;
      DWORD dwOSVersionInfoSize; //  ˆ this ";" must be added
      DWORD dwMajorVersion;
      DWORD dwMinorVersion;
      DWORD dwBuildNumber;
      DWORD dwPlatformId;
      TCHAR szCSDVersion[128];
      WORD wServicePackMajor;
      WORD wServicePackMinor;
      WORD wSuiteMask;
      BYTE wProductType;
      BYTE wReserved;
   } OSVERSIONINFOEX, *POSVERSIONINFOEX, *LPOSVERSIONINFOEX;

   #define DC_CALL_STD            0x0020

   PROCEDURE Main
      LOCAL oVerInfo

      // Create OSVERSIONINFOEX structure object
      oVerInfo := (struct OSVERSIONINFOEX)

      // assign structure size to structure member
      oVerInfo:dwOSVersionInfoSize := oVerInfo:sizeOf()

      // pass structure object by reference to DllCall()
      // (it is an OUT parameter)
      DllCall( "Kernel32.dll", DC_CALL_STD , ;
               "GetVersionEx", @oVerInfo )

      // display result of API
      ? oVerInfo:dwMajorVersion            // result:    5
      ? oVerInfo:dwMinorVersion            // result:    1
      ? oVerInfo:dwBuildNumber             // result: 2006

      // this member contains a byte array
      // retrieve it as character string
      ? oVerInfo:szCSDVersion:asString()   // result: Service Pack 2
   RETURN