====== win32std - Windows binding for PHP ======

win32std is a set of function that hook into the [[msdn>Windows API]]. 
It's purpose in not 'to expose all win32 function known to man'(tm) but to expose the most usefull.

It's an open project, feel free to sugest new functionnality to the [[http://pecl.php.net|PECL]] [[pecl>support.php|mailling list]].

All suggestion is welcome but for Windows GUI function please first look at [[SF>Winbinder]].

If you do client scripting under Windows you should also look at [[php_dhtml:index|php_dhtml]] on this site.

win32std is licensed under the [[http://www.php.net/license/3_0.txt|PHP Licence version 3]].

===== Links =====

  * [[HOWTO:Embeding a PHP source into a Windows executable file]] using win32std and the embed SAPI (HOWTO)
  * [[Embeder]] an utility to build a Windows executable file without a compiler

===== Features =====

  * Common Win32 dialogs.
  * Wrapper for some standard functions.
  * Registry access ([[php-guy>fmk|Frank M. Kromann]]).
  * Windows binary [[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/windowsuserinterface/resources.asp|resources]] access (r/w)
  * Resource access stream wrapper (read only). Compatible with the [[http://msdn.microsoft.com/workshop/networking/predefined/res.asp|res protocol]].

===== Support & Bugs & Download =====

You can reach all of that at the win32std [[pecl>win32std|Project page at PECL]].

There also direct download links in the [[:downloads]] page.


There is also a (recent) [[TODO]].

===== API Documentation =====

==== Common Win32 dialogs ====

  * **int win_message_box( $text[, $type, $caption] )**
Prompt a typical Win32 message box.
Use the Messages Box Constants to modify the appearance of the message box.

<code php>
switch( win_message_box( "Nice messagebox isn't it ?", MB_YESNOCANCEL | MB_DEFBUTTON2 | MB_ICONQUESTION, 'Caption' ) ) {
	case MB_IDYES:
		echo 'Yes selected';
		break;
	case MB_IDNO:
		echo 'No selected';
		break;
	case MB_IDCANCEL:
		echo 'Cancel selected';
		break;
}
</code>

  * **int win_browse_folder( [string $dir, string $caption=""] **
Prompt a "browse for folder" message box

<code php>
$result= win_browse_folder('%WINDIR%', 'Please select a directory');
if( !$result ) echo 'No directory selected';
else {
	echo "Directory '$result' selected";
}
</code>

  * **string win_browse_file( $open[, $path, $filename, $ext, $filter] )**
Pop an open or save dialog box,
You can specify a starting path, a default filename, a default extension, and a filter.

The filter is in the [[msdn>OPENFILENAME|MS format]] or in the win32std format (see below).
  Filter in MS format: "HTML File\0*.htm;*.html\0INI file\0*.ini\0All files\0*.*\0\0"

<code php>
$filter= array( 
	"HTML Files" => "*.htm;*.html", 
	"INI Files" => "*.ini", 
	"All files" => "*.*" 
	);

$result= win_browse_file(true, '%WINDIR%', 'a_file_name', null, $filter);
if( !$result ) echo 'No file selected';
else {
	echo "File '$result' selected";
}
</code>

==== Windows utility functions ====

  * **bool win_shell_execute(string $absolute_path[, string $action, string $args, string $dir])**
Execute a shell action on a file or directory.
Common actions: open, edit, explore, find, print, properties.
The shell act the same way when you double click on an icon (action=NULL) or when you choose a menu item on the right click button.
This way you can also execute programs that are totaly detached from the current one (useful with DirectX games for exemple).

<code php>
win_shell_execute( 'c:\\', "find" );
win_shell_execute( 'word_file.doc', "print" );
</code>


  * **win_play_wav( string $file[, bool $loop])**
file may be either NULL to stop playback or a file name to start it
loop can be set to loop playback (default to false)
module may be opened by res_open a file must represent the resource id (NOT IMPL)

<code php>
if( !win_play_wav( "%WINDIR%\\Media\\ringin.wav", 1 ) ) 
	echo "Unable to play sound !\n";
else {
	echo "Playing sound !\n";
	sleep(1);
	if( !win_play_wav( NULL ) )
		echo "Unable to stop playing sound !\n";
	else
		echo "Play stopped !\n";
} 
</code>

  * **win_beep(string $type)**
  plays the system sound used by default for pre-defined events:
    '*': System Asterisk 
    '!': System Exclamation 
    'H': System Hand 
    '?': System Question 
    '1': System Default 
    '0': Standard beep using the computer speaker%%

<code php>
win_beep('*');
</code>

  * **int win_create_link( $file, $link_file, $args, $descr, $workingdir )**
Create a MS link file (.lnk) 
Don't forget the .lnk at the end of link_file or the link will not work.

==== Registry access ====

  * **resource reg_open_key(mixed $hKey, string $subkey [, int $samDesired = KEY_ALL_ACCESS])**
Open a registry key

  * **resource reg_create_key(mixed $hKey, string $subkey [, int $samDesired = KEY_ALL_ACCESS])**
Create a sub key

  * **void reg_close_key(resource $hKey)**
Close a registry key

  * **mixed reg_enum_key(mixed $hKey[, int $index=1])**
Return the 'index' based sub key.
Return false when done.

  * **mixed reg_enum_value(mixed $hKey[, int $index=-1])**
Return the 'index' based value.
Return false when done.

  * **bool reg_set_value(mixed $hKey, string $value_name, int $type, mixed $value)**
Set a value.

  * **mixed reg_get_value(mixed $hKey, string $value_name)**
Get a value.


<code php>
$strMainKey= 'Control Panel';
$mainKey= reg_open_key( HKEY_CURRENT_USER, $strMainKey );
if( !$mainKey ) err( "Can't open '$strMainKey' !" );
echo "'$strMainKey' Key opened\n\nKeys:\n";
print_r( reg_enum_key($mainKey) );
for( $i= 0; $key= reg_enum_key($mainKey, $i); $i++ ) {
	echo "\t$key\n";
}
echo "\nValues:\n";
print_r( reg_enum_value($mainKey) );
for( $i= 0; $value= reg_enum_value($mainKey, $i); $i++ ) {
	echo "\t$value=".reg_get_value($mainKey, $value)."\n";
}
reg_close_key($mainKey);
</code>


==== Windows resources ====

  * **resource res_open( $module_name )**
Return a PHP resource that identify the Windows resource module handle.
A module is either a dll file or an exe file.

  * **bool res_close( resource $module )**
Close a module handle

  * **string res_get( resource $module, string $type, string $name[, int $lang] )**
Get a resource data.
lang is not fully supported but 0 means neutral, 1 is user default, 2 is system default (see winnt.h LANG_* & SUBLANG_*).

  * **bool res_set( string $file, string $type, string $name, string $data[, int $lang] )**
Add or modify a resource in 'file' (dll or exe)
lang is not fully supported: 0 means neutral, 1 is user default, 2 is system default (see winnt.h LANG_* & SUBLANG_*).

Fail if the file is in use (if the executable is in use for exemple).

  * **array res_list( resource $module, string $type )**
return the resource list for a given type.

  * **array res_list_type( resource $module [, bool $as_string=true] )**
return the resource type list for a given module.
as_string specify if known type should be translated to string (but such string can't be used in res_get)


<code php>
$file= realpath('test_resourceDll.dll');
if( empty($file) ) die('The res exemple need a file !');
res_set( $file, 'A_TYPE', 'A_RC_NAME', 'The time: '.date('d-m-Y h:i') );

echo "Res Stream read: ".file_get_contents('res://'.$file.'/A_TYPE/A_RC_NAME')."\n\n";

$h= res_open( $file );
if( !$h ) err( "can't open ".$file );


echo "Res list of '$file': \n";
$list= res_list_type($h, true);
if( $list===FALSE ) err( "Can't list type" );

for( $i= 0; $i<count($list); $i++ ) {
	echo $list[$i]."\n";
	$res= res_list($h, $list[$i]);
	for( $j= 0; $j<count($res); $j++ ) {
		echo "\t".$res[$j]."\n";
	}
}
echo "Res get: ".res_get( $h, 'A_TYPE', 'A_RC_NAME' )."\n\n";
res_close( $h );
</code>


==== Constants ====

=== Message box type ===
<code php>
MB_OK
MB_OKCANCEL
MB_RETRYCANCEL
MB_YESNO
MB_YESNOCANCEL
</code>

=== Message box icon ===
<code php>
MB_ICONEXCLAMATION
MB_ICONWARNING
MB_ICONINFORMATION
MB_ICONASTERISK
MB_ICONQUESTION
MB_ICONSTOP
MB_ICONERROR
MB_ICONHAND
</code>

=== Message box default button ===
<code php>
MB_DEFBUTTON1
MB_DEFBUTTON2
MB_DEFBUTTON3
MB_DEFBUTTON4
</code>

=== Message box return ===
<code php>
MB_IDABORT
MB_IDCANCEL
MB_IDNO
MB_IDOK
MB_IDYES
MB_IDIGNORE
MB_IDRETRY
</code>

=== Registry main key ===
<code php>
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS
</code>

=== Registry access type ===
<code php>
KEY_ALL_ACCESS
KEY_WRITE
KEY_READ
</code>

=== Registry value type ===
<code php>
REG_BINARY
REG_DWORD
REG_EXPAND_SZ
REG_MULTI_SZ
REG_NONE
REG_SZ
</code>

=== resource types ===
<code php>
RT_CURSOR="#1"
RT_BITMAP="#2"
RT_ICON="#3"
RT_MENU="#4"
RT_DIALOG="#5"
RT_STRING="#6"
RT_FONTDIR="#7"
RT_FONT="#8"
RT_ACCELERATOR="#9"
RT_RCDATA="#10"
RT_MESSAGETABLE="#11"
RT_GROUP_CURSOR="#12"
RT_GROUP_ICON="#14"
RT_VERSION="#16"
RT_DLGINCLUDE="#17"
RT_PLUGPLAY="#19"
RT_VXD="#20"
RT_ANICURSOR="#21"
RT_ANIICON="#22"
RT_HTML="#23"
</code>