[PATCH] Bump Locale-Codes from 3.38 to 3.39

[perl5.git] / cpan / Win32API-File / buffers.h

/* buffers.h -- Version 1.11 */\r
\r
/* The following abbreviations are used at start of parameter names\r
 * to indicate the type of data:\r
 *	s	string (char * or WCHAR *) [PV]\r
 *	sw	wide string (WCHAR *) [PV]\r
 *	p	pointer (usually to some structure) [PV]\r
 *	a	array (packed array as in C) (usually of some structure) [PV]\r
 *		    called a "vector" or "vect" in some places.\r
 *	n	generic number [IV, UV, or NV]\r
 *	iv	signed integral value [IV]\r
 *	u	unsigned integral value [UV]\r
 *	d	floating-point number (double) [NV]\r
 *	b	boolean (bool) [IV]\r
 *	c	count of items [UV]\r
 *	l	length (in bytes) [UV]\r
 *	lw	length in WCHARs [UV]\r
 *	h	a handle [IV]\r
 *	r	record (structure) [PV]\r
 *	sv	Perl scalar (s, i, u, d, n, or rv) [SV]\r
 *	rv	Perl reference (usually to scalar) [RV]\r
 *	hv	reference to Perl hash [HV]\r
 *	av	reference to Perl array [AV]\r
 *	cv	Perl code reference [PVCV]\r
 *\r
 * Unusual combined types:\r
 *	pp	single pointer (to non-Perl data) packed into string [PV]\r
 *	pap	vector of pointers (to non-Perl data) packed into string [PV]\r
 *\r
 * Whether a parameter is for input data, output data, or both is usually\r
 * not reflected by the data type prefix.  In cases where this is not\r
 * obvious nor reflected in the variable name proper, you can use\r
 * the following in front of the data type prefix:\r
 *	i	an input parameter given to API (usually omitted)\r
 *	o	an Output parameter taken from API\r
 *	io	Input given to API then overwritten with Output taken from API\r
 */\r
\r
/* Buffer arguments are usually followed by an argument (or two) specifying\r
 * their size and/or returning the size of data written.  The size can be\r
 * measured in bytes ["lSize"] or in characters [for (char *) buffers such as\r
 * for *A() routines, these sizes are also called "lSize", but are called\r
 * "lwSize" for (WCHAR *) buffers, UNICODE strings, such as for *W() routines].\r
 *\r
 * Before calling the actual C function, you must make sure the Perl variable\r
 * actually has a big enough buffer allocated, and, if the user didn't want\r
 * to specify a buffer size, set the buffer size to be correct.  This is what\r
 * the grow_*() macros are for.  They also handle special meanings of the\r
 * buffer size argument [described below].\r
 *\r
 * Once the actual C function returns, you must set the Perl variable to know\r
 * the size of the written data.  This is what the trunc_*() macros are for.\r
 *\r
 * The size sometimes does and sometimes doesn't include the trailing '\0'\r
 * [or L'\0'], so we always add or subtract 1 in the appropriate places so\r
 * we don't care about this detail.\r
 *\r
 * A call may  1) request a pointer to the buffer size which means that\r
 * the buffer size will be overwritten with the size of the data written;\r
 * 2) have an extra argument which is a pointer to the place to write the\r
 * size of the written data;  3) provide the size of the written data in\r
 * the function's return value;  4) format the data so that the length\r
 * can be determined by examining the data [such as with '\0'-terminated\r
 * strings];  or  5) write fixed-length data [usually sizeof(STRUCT)].\r
 * This obviously determines what you should use in the trunc_*() macro\r
 # to specify the size of the output value.\r
 *\r
 * The user can pass in an empty list reference, C<[]>, to indicate C<NULL>\r
 * for the pointer to the buffer which means that they don't want that data.\r
 *\r
 * The user can pass in C<[]> or C<0> to indicate that they don't care about\r
 * the buffer size [we aren't programming in C here, after all] and just try\r
 * to get the data.  This will work if either the buffer already allocated for\r
 * the SV [scalar value] is large enough to hold the data or the API provides\r
 * an easy way to determine the required size [and the XS code uses it].\r
 *\r
 * If the user passes in a numeric value for a buffer size, then the XS\r
 * code makes sure that the buffer is at least large enough to hold a value\r
 * of that size and then passes in how large the buffer is.  So the buffer\r
 * size passed to the API call is the larger of the size requested by the\r
 * user and the size of the buffer already allocated to the SV.\r
 *\r
 * The user can also pass in a string consisting of a leading "=" followed\r
 * by digits for a buffer size.  This means just use the size specified after\r
 * the equals sign, even if the allocated buffer is larger.  The XS code will\r
 * still allocate a large enough buffer before the first call.\r
 *\r
 * If the function is nice enough to tell us that a buffer was too small\r
 * [usually via ERROR_MORE_DATA] _and_ how large the buffer needs to be,\r
 * then the XS code should enlarge the buffer(s) and repeat the call [once].\r
 * This resizing is _not_ done for buffers whose size was specified with a\r
 * leading "=".\r
 *\r
 * Only grow_buf() and perhaps trunc_buf() can be used in a typemap file.\r
 * The other macros would be used in the parameter declarations or INPUT:\r
 * section [grow_*()], the INIT: section [init_*()], or the OUTPUT: section\r
 * [trunc_*()].\r
 *\r
 * Buffer arguments should be initialised with C<= NO_INIT> [or C<= NULL;>].\r
 *\r
 * See also the F<typemap> file.  C<oDWORD>, for example, is for an output-\r
 * only parameter of type C<DWORD> and you should simply C<#define> it to be\r
 * C<DWORD>.  In F<typemap>, C<oDWORD> is treated differently than C<DWORD>\r
 * in two ways.\r
 *\r
 * First, if C<undef> is passed in, a C<DWORD> could generate a warning\r
 * when it gets converted to 0 while C<oDWORD> will never generate such a\r
 * warning for C<undef>.  This first difference doesn't apply if specific\r
 * initialization is specified for the variable, as in C<= init_buf_l($var);>.\r
 * In particular, the init_*() macros also convert C<undef> to 0 without\r
 * ever producing a warning.\r
 *\r
 * Second, passing in a read-only SV for a C<oDWORD> parameter will generate\r
 * a fatal error on output when we try to update the SV.  For C<DWORD>, we\r
 * won't update a read-only SV since passing in a literal constant for a\r
 * buffer size is a useful thing to do even though it prevents us from\r
 * returning the size of data written via that SV.  Since we should use a\r
 * trunc_*() macro to output the actual data, the user should be able to\r
 * determine the size of data written based on the size of the scalar we\r
 * output anyway.\r
 *\r
 * This second difference doesn't apply unless the parameter is listed in\r
 * the OUTPUT: section without specific output instructions.  We define\r
 * no macros for outputting buffer length parameters so be careful to use\r
 * C<oDWORD> [for example] for them if and only if they are output-only.\r
 *\r
 * Note that C<oDWORD> is the same as C<DWORD> in that, if a defined value\r
 * is passed in, it is used [and can generate a warning if the value is\r
 * "not numeric"].  So although C<oDWORD> is for output-only parameters,\r
 * we still initialize the C variable before calling the API.  This is good\r
 * in case the parameter isn't always strictly output-only due to upgrades,\r
 * bugs, etc.\r
 *\r
 * Here is a made-up example that shows several cases:\r
 *\r
 * # Actual GetDataW() returns length of data written to ioswName, not bool.\r
 * bool\r
 * GetDataW( ioswName, ilwName, oswText, iolwText, opJunk, opRec, ilRec, olRec )\r
 *	WCHAR *	ioswName	= NO_INIT\r
 *	DWORD	ilwName		= NO_INIT\r
 *	WCHAR *	oswText		= NO_INIT\r
 *	DWORD	&iolwText	= init_buf_l($arg);\r
 *	void *	opJunk		= NO_INIT\r
 *	BYTE *	opRec		= NO_INIT\r
 *	DWORD	ilRec		= init_buf_l($arg);\r
 *	oDWORD	&olRec\r
 * PREINIT:\r
 *	DWORD	olwName;\r
 * INIT:\r
 *	grow_buf_lw( ioswName,ST(0), ilwName,ST(1) );\r
 *	grow_buf_lw( oswText,ST(2), iolwText,ST(3) );\r
 *	grow_buf_typ( opJunk,ST(4),void *, LONG_STRUCT_TYPEDEF );\r
 *	grow_buf_l( opRec,ST(5),BYTE *, ilRec,ST(6) );\r
 * CODE:\r
 *	olwName= GetDataW( ioswName, ilwName, oswText, &iolwText,\r
 *			   (LONG_STRUCT_TYPEDEF *)opJunk, opRec, &iolRec );\r
 *	if(  0 == olwName  &&  ERROR_MORE_DATA == GetLastError()\r
 *	 &&  ( autosize(ST(1)) || autosize(ST(3)) || autosize(ST(6)) )  ) {\r
 *	    if(  autosize(ST(1))  )\r
 *		grow_buf_lw( ioswName,ST(0), ilwName,ST(1) );\r
 *	    if(  autosize(ST(3))  )\r
 *		grow_buf_lw( oswText,ST(2), iolwText,ST(3) );\r
 *	    if(  autosize(ST(6))  )\r
 *		grow_buf_l( opRec,ST(5),BYTE *, iolRec,ST(6) );\r
 *	    olwName= GetDataW( ioswName, ilwName, oswText, &iolwText,\r
 *			       (LONG_STRUCT_TYPEDEF *)opJunk, opRec, &iolRec );\r
 *	}\r
 *	RETVAL=  0 != olwName;\r
 * OUTPUT:\r
 *	RETVAL\r
 *	ioswName	trunc_buf_lw( RETVAL, ioswName,ST(0), olwName );\r
 *	oswText		trunc_buf_lw( RETVAL, oswText,ST(2), iolwText );\r
 *	iolwText\r
 *	opJunk		trunc_buf_typ(RETVAL,opJunk,ST(4),LONG_STRUCT_TYPEDEF);\r
 *	opRec		trunc_buf_l( RETVAL, opRec,ST(5), olRec );\r
 *	olRec\r
 *\r
 * The above example would be more complex and less efficient if we used\r
 * C<DWORD * iolwText> in place of C<DWORD  &iolwText>.  The only possible\r
 * advantage would be that C<NULL> would be passed in for C<iolwText> if\r
 * _both_ C<$oswText> and C<$iolwText> were specified as C<[]>.  The *_pl*()\r
 * macros are defined [and C<DWORD *> specified in F<typemap>] so we can\r
 * handle those cases but it is usually better to use the *_l*() macros\r
 * instead by specifying C<&> instead of C<*>.  Using C<&> instead of C<*>\r
 * is usually better when dealing with scalars, even if they aren't buffer\r
 * sizes.  But you must use C<*> if it is important for that parameter to\r
 * be able to pass C<NULL> to the underlying API.\r
 *\r
 * In Win32API::, we try to use C<*> for buffer sizes of optional buffers\r
 * and C<&> for buffer sizes of required buffers.\r
 *\r
 * For parameters that are pointers to things other than buffers or buffer\r
 * sizes, we use C<*> for "important" parameters [so that using C<[]>\r
 * generates an error rather than fetching the value and just throwing it\r
 * away], and for optional parameters [in case specifying C<NULL> is or\r
 * becomes important].  Otherwise we use C<&> [for "unimportant" but\r
 * required parameters] so the user can specify C<[]> if they don't care\r
 * about it.  The output handle of an "open" routine is "important".\r
 */\r
\r
#ifndef Debug\r
# define	Debug(list)	/*Nothing*/\r
#endif\r
\r
/*#ifndef CAST\r
 *# ifdef __cplusplus\r
 *#  define   CAST(type,expr)	static_cast<type>(expr)\r
 *# else*/\r
#  define   CAST(type,expr)	(type)(expr)\r
/*# endif\r
 *#endif*/\r
\r
/* Is an argument C<[]>, meaning we should pass C<NULL>? */\r
#define null_arg(sv)	(  SvROK(sv)  &&  SVt_PVAV == SvTYPE(SvRV(sv))	\\r
			   &&  -1 == av_len((AV*)SvRV(sv))  )\r
\r
#define PV_or_null(sv)	( null_arg(sv) ? NULL : SvPV_nolen(sv) )\r
\r
/* Minimum buffer size to use when no buffer existed: */\r
#define MIN_GROW_SIZE	128\r
\r
#ifdef Debug\r
/* Used in Debug() messages to show which macro call is involved: */\r
#define string(arg) #arg\r
#endif\r
\r
/* Simplify using SvGROW() for byte-sized buffers: */\r
#define lSvGROW(sv,n)	SvGROW( sv, 0==(n) ? MIN_GROW_SIZE : (n)+1 )\r
\r
/* Simplify using SvGROW() for WCHAR-sized buffers: */\r
#define lwSvGROW(sv,n)	CAST( WCHAR *,		\\r
	SvGROW( sv, sizeof(WCHAR)*( 0==(n) ? MIN_GROW_SIZE : (n)+1 ) ) )\r
\r
/* Whether the buffer size we got lets us change what buffer size we use: */\r
#define autosize(sv)	(!(  SvOK(sv)  &&  ! SvROK(sv)		\\r
			 &&  SvPV_nolen(sv)  &&  '=' == *SvPV_nolen(sv)  ))\r
\r
/* Get the IV/UV for a parameter that might be C<[]> or C<undef>: */\r
#define optIV(sv)	( null_arg(sv) ? 0 : !SvOK(sv) ? 0 : SvIV(sv) )\r
#define optUV(sv)	( null_arg(sv) ? 0 : !SvOK(sv) ? 0 : SvUV(sv) )\r
\r
/* Allocate temporary storage that will automatically be freed later: */\r
#ifndef TempAlloc	/* Can be C<#define>d to be C<_alloca>, for example */\r
# define TempAlloc( size )	sv_grow( sv_newmortal(), size )\r
#endif\r
\r
/* Initialize a buffer size argument of type (DWORD *): */\r
#define init_buf_pl( plSize, svSize, tpSize )		STMT_START {	\\r
	if(  null_arg(svSize)  )					\\r
	    plSize= NULL;						\\r
	else {								\\r
	    STRLEN n_a;							\\r
	    *( plSize= CAST( tpSize, TempAlloc(sizeof(*plSize)) ) )=	\\r
	      autosize(svSize) ? optUV(svSize)				\\r
	        : strtoul( 1+SvPV(svSize,n_a), NULL, 10 );		\\r
	} } STMT_END\r
/* In INPUT section put ": init_buf_pl($var,$arg,$type);" after var name. */\r
\r
/* Initialize a buffer size argument of type DWORD: */\r
#define init_buf_l( svSize )						\\r
	(  null_arg(svSize) ? 0 : autosize(svSize) ? optUV(svSize)	\\r
	   : strtoul( 1+SvPV_nolen(svSize), NULL, 10 )  )\r
/* In INPUT section put "= init_buf_l($arg);" after variable name. */\r
\r
/* Lengths in WCHARs are initialized the same as lengths in bytes: */\r
#define init_buf_plw	init_buf_pl\r
#define init_buf_lw	init_buf_l\r
\r
/* grow_buf_pl() and grow_buf_plw() are included so you can define\r
 * parameters of type C<DWORD *>, for example.  In practice, it is\r
 * usually better to define such parameters as "DWORD &". */\r
\r
/* Grow a buffer where we have a pointer to its size in bytes: */\r
#define	grow_buf_pl( sBuf,svBuf,tpBuf, plSize,svSize,tpSize ) STMT_START { \\r
	Debug(("grow_buf_pl( %s==0x%lX,[%s:%ld/%ld, %s==0x%lX:%ld,[%s )\n",\\r
	  string(sBuf),sBuf,strchr(string(svBuf),'('),SvPOK(svBuf)?	\\r
	  SvCUR(svBuf):-1,SvPOK(svBuf)?SvLEN(svBuf):-1,string(plSize),	\\r
	  plSize,plSize?*plSize:-1,strchr(string(svSize),'(')));	\\r
	if(  null_arg(svBuf)  ) {					\\r
	    sBuf= NULL;							\\r
	} else {							\\r
	    STRLEN n_a;							\\r
	    if(  NULL == plSize  )					\\r
		*( plSize= CAST(tpSize,TempAlloc(sizeof(*plSize))) )= 0;\\r
	    if(  ! SvOK(svBuf)  )    sv_setpvn(svBuf,"",0);		\\r
	    (void) SvPV_force( svBuf, n_a );				\\r
	    sBuf= CAST( tpBuf, lSvGROW( svBuf, *plSize ) );		\\r
	    if(  autosize(svSize)  )   *plSize= SvLEN(svBuf) - 1;	\\r
	    Debug(("more buf_pl( %s==0x%lX,[%s:%ld/%ld, %s==0x%lX:%ld,[%s )\n",\\r
	      string(sBuf),sBuf,strchr(string(svBuf),'('),SvPOK(svBuf)?	\\r
	      SvCUR(svBuf):-1,SvPOK(svBuf)?SvLEN(svBuf):-1,string(plSize),\\r
	      plSize,plSize?*plSize:-1,strchr(string(svSize),'(')));	\\r
	} } STMT_END\r
\r
/* Grow a buffer where we have a pointer to its size in WCHARs: */\r
#define	grow_buf_plw( sBuf,svBuf, plwSize,svSize,tpSize ) STMT_START {	\\r
	if(  null_arg(svBuf)  ) {					\\r
	    sBuf= NULL;							\\r
	} else {							\\r
	    STRLEN n_a;							\\r
	    if(  NULL == plwSize  )					\\r
		*( plwSize= CAST(tpSize,TempAlloc(sizeof(*plwSize))) )= 0;\\r
	    if(  ! SvOK(svBuf)  )    sv_setpvn(svBuf,"",0);		\\r
	    (void) SvPV_force( svBuf, n_a );				\\r
	    sBuf= lwSvGROW( svBuf, *plwSize );				\\r
	    if(  autosize(svSize)  )					\\r
		*plwSize= SvLEN(svBuf)/sizeof(WCHAR) - 1;		\\r
	} } STMT_END\r
\r
/* Grow a buffer where we have its size in bytes: */\r
#define	grow_buf_l( sBuf,svBuf,tpBuf, lSize,svSize )	STMT_START {	\\r
	if(  null_arg(svBuf)  ) {					\\r
	    sBuf= NULL;							\\r
	} else {							\\r
	    STRLEN n_a;							\\r
	    if(  ! SvOK(svBuf)  )    sv_setpvn(svBuf,"",0);		\\r
	    (void) SvPV_force( svBuf, n_a );				\\r
	    sBuf= CAST( tpBuf, lSvGROW( svBuf, lSize ) );		\\r
	    if(  autosize(svSize)  )   lSize= SvLEN(svBuf) - 1;		\\r
	} } STMT_END\r
\r
/* Grow a buffer where we have its size in WCHARs: */\r
#define	grow_buf_lw( swBuf,svBuf, lwSize,svSize )	STMT_START {	\\r
	if(  null_arg(svBuf)  ) {					\\r
	    swBuf= NULL;						\\r
	} else {							\\r
	    STRLEN n_a;							\\r
	    if(  ! SvOK(svBuf)  )    sv_setpvn(svBuf,"",0);		\\r
	    (void) SvPV_force( svBuf, n_a );				\\r
	    swBuf= lwSvGROW( svBuf, lwSize );				\\r
	    if(  autosize(svSize)  )					\\r
		lwSize= SvLEN(svBuf)/sizeof(WCHAR) - 1;			\\r
	} } STMT_END\r
\r
/* Grow a buffer that contains the declared fixed data type: */\r
#define	grow_buf( pBuf,svBuf, tpBuf )			STMT_START {	\\r
	if(  null_arg(svBuf)  ) {					\\r
	    pBuf= NULL;							\\r
	} else {							\\r
	    STRLEN n_a;							\\r
	    if(  ! SvOK(svBuf)  )    sv_setpvn(svBuf,"",0);		\\r
	    (void) SvPV_force( svBuf, n_a );				\\r
	    pBuf= CAST( tpBuf, SvGROW( svBuf, sizeof(*pBuf) ) );	\\r
	} } STMT_END\r
\r
/* Grow a buffer that contains a fixed data type other than that declared: */\r
#define	grow_buf_typ( pBuf,svBuf,tpBuf, Type )		STMT_START {	\\r
	if(  null_arg(svBuf)  ) {					\\r
	    pBuf= NULL;							\\r
	} else {							\\r
	    STRLEN n_a;							\\r
	    if(  ! SvOK(svBuf)  )    sv_setpvn(svBuf,"",0);		\\r
	    (void) SvPV_force( svBuf, n_a );				\\r
	    pBuf= CAST( tpBuf, SvGROW( svBuf, sizeof(Type) ) );	\\r
	} } STMT_END\r
\r
/* Grow a buffer that contains a list of items of the declared data type: */\r
#define	grow_vect( pBuf,svBuf,tpBuf, cItems )		STMT_START {	\\r
	if(  null_arg(svBuf)  ) {					\\r
	    pBuf= NULL;							\\r
	} else {							\\r
	    STRLEN n_a;							\\r
	    if(  ! SvOK(svBuf)  )    sv_setpvn(svBuf,"",0);		\\r
	    (void) SvPV_force( svBuf, n_a );				\\r
	    pBuf= CAST( tpBuf, SvGROW( svBuf, sizeof(*pBuf)*cItems ) );	\\r
	} } STMT_END\r
\r
/* If call succeeded, set data length to returned length (in bytes): */\r
#define	trunc_buf_l( bOkay, sBuf,svBuf, lSize )		STMT_START {	\\r
	if(  bOkay  &&  NULL != sBuf  ) {				\\r
	    SvPOK_only( svBuf );					\\r
	    SvCUR_set( svBuf, lSize );					\\r
	} } STMT_END\r
\r
/* Same as above except we have a pointer to the returned length: */\r
#define	trunc_buf_pl( bOkay, sBuf,svBuf, plSize )			\\r
	trunc_buf_l( bOkay, sBuf,svBuf, *plSize )\r
\r
/* If call succeeded, set data length to returned length (in WCHARs): */\r
#define	trunc_buf_lw( bOkay, sBuf,svBuf, lwSize )	STMT_START {	\\r
	if(  bOkay  &&  NULL != sBuf  ) {				\\r
	    SvPOK_only( svBuf );					\\r
	    SvCUR_set( svBuf, (lwSize)*sizeof(WCHAR) );			\\r
	} } STMT_END\r
\r
/* Same as above except we have a pointer to the returned length: */\r
#define	trunc_buf_plw( bOkay, swBuf,svBuf, plwSize )			\\r
	trunc_buf_lw( bOkay, swBuf,svBuf, *plwSize )\r
\r
/* Set data length for a buffer that contains the declared fixed data type: */\r
#define	trunc_buf( bOkay, pBuf,svBuf )			STMT_START {	\\r
	if(  bOkay  &&  NULL != pBuf  ) {				\\r
	    SvPOK_only( svBuf );					\\r
	    SvCUR_set( svBuf, sizeof(*pBuf) );				\\r
	} } STMT_END\r
\r
/* Set data length for a buffer that contains some other fixed data type: */\r
#define	trunc_buf_typ( bOkay, pBuf,svBuf, Type )	STMT_START {	\\r
	if(  bOkay  &&  NULL != pBuf  ) {				\\r
	    SvPOK_only( svBuf );					\\r
	    SvCUR_set( svBuf, sizeof(Type) );				\\r
	} } STMT_END\r
\r
/* Set length for buffer that contains list of items of the declared type: */\r
#define	trunc_vect( bOkay, pBuf,svBuf, cItems )		STMT_START {	\\r
	if(  bOkay  &&  NULL != pBuf  ) {				\\r
	    SvPOK_only( svBuf );					\\r
	    SvCUR_set( svBuf, sizeof(*pBuf)*cItems );			\\r
	} } STMT_END\r
\r
/* Set data length for a buffer where a '\0'-terminate string was stored: */\r
#define	trunc_buf_z( bOkay, sBuf,svBuf )		STMT_START {	\\r
	if(  bOkay  &&  NULL != sBuf  ) {				\\r
	    SvPOK_only( svBuf );					\\r
	    SvCUR_set( svBuf, strlen(sBuf) );				\\r
	} } STMT_END\r
\r
/* Set data length for a buffer where a L'\0'-terminate string was stored: */\r
#define	trunc_buf_zw( bOkay, sBuf,svBuf )		STMT_START {	\\r
	if(  bOkay  &&  NULL != sBuf  ) {				\\r
	    SvPOK_only( svBuf );					\\r
	    SvCUR_set( svBuf, wcslen(sBuf)*sizeof(WCHAR) );		\\r
	} } STMT_END\r