Perl Module Extensions for Win32

Goals

This document describes the interface for two of the Module Extensions being written by hip communications.

There are more on the way!

Conventions

The following conventions are used throughout this document.

• Command line arguments:

[argname] Describes an optional argument.

(out) argname Indicates the method requires a reference for this argument. This

value will be where the result of the call is stored.

• Return values

All methods and functions return TRUE on success. If an error occurs

the Perl built in variable, '$!' is set.

Table of Contents

NT::EventLog

NT::Registry

NT::EventLog

Functions

Open( (out) $EventObj, $SourceName, [$ServerName]);

(out) $EventObj; Reference to an EventLog Object.

$SourceName; Name of the source of the event.

$ServerName; Optional: name of machine. If none, assumes local.

Open an eventlog, and return the object in the $eventobj reference.

$servername is optional. if not given, the local machine is used.

OpenBackup( (out)$EventObj, $FileName, [$ServerName]);

(out)$EventObj Reference to an Eventlog Object.

$FileName name of the file containing the backup eventlog.

$ServerName Optional: UNC name of the server containing the backup log.

Open a backup eventlog and return an object to control it. If $ServerName is not given the local machine is used.

methods

Backup( $filename )

Save the current open event log to a file

Read($ReadFlags,$RecordOffset,(out)%EventInfo)

(out) $ReadFlags Specifies how to read log

$RecordOffset, Number of first record

(out)%EventInfo Event information

The Read method reads an entry from the eventlog. $ReadFlags can be any combination of:

• EVENTLOG_FORWARDS_READ
• EVENTLOG_BACKWARDS_READ
• EVENTLOG_SEEK_READ
• EVENTLOG_SEQUENTIAL_READ

See the Report method for information on the %EventInfo hash.

Report( $Event, %EventInfo )

$Event A scalar defining the type of event.

%EventInfo A hash containing the event info.

Reports an event. Implicitly calls RegisterEventSource.

The options for $Event are:

• EVENTLOG_ERROR_TYPE
• EVENTLOG_WARNING_TYPE
• EVENTLOG_INFORMATION_TYPE
• EVENTLOG_AUDIT_SUCCESS_TYPE
• EVENTLOG_AUDIT_FAILURE_TYPE

%EventInfo contains the following:

Key:            Value:                                     

Category        integer value for the category of the      
                event (app defined )                       

EventID         ID value of the Event. Source specific,    
                any value.                                 

EventRawData    The Raw binary data                        

Strings         Any text strings to merge                  

user            user name.                                 

GetOldest( (out) $oldest );

Returns the Absolute record number of the oldest record in the event log.

GetNumber( (out) $NumberOfEvents )

Returns the number of events.

Clear( [ $filename ] )

If the $filename option is given, then the current eventlog is written to the file

Clears the event log.

GetSD( (out) $SecurityDescriptor )

Returns the security descriptor object for the current event log.

Example 1

	use NT::Eventlog;
	#use is necessary since the Eventlog module exports 
#constants into the main:: namespace.
sub TEST1{ 
my $number, $EventLog; 
Open NT::EventLog ( $EventLog , "System")|| die $!;
$EventLog->GetNumberOfEvents( $number )|| die $!; 
print "There are $number records in the System Event Log\n";} 

Example 2

sub TEST2{ 
# define the event to log. 
my $number, $EventLog; 
%Event = { 'EventType' => ERROR; 
'Category' => 0; 
'EventID' => 0x1003; 
'EventRawData' => NULL; 
'Strings' =>"SampleApp"; 
}
# open the event log.
 OpenEventObj ( $EventLog , "SamplApp")||die $!;
#report the event and check the error 
$EventLog->ReportEvent( %Event )||die $!;}
	}

NT::Registry

methods

open( (out)RegistryObj,$key );

(out)RegistryObj Reference to a reference object

$key Pre-defined key.

Open the specified registry key and create an object to access the key. If the specified key does not exist, it is not created.$Key can hold any already opened key.

When the Registry module is loaded, four Registry objects are created.

The predefined registry objects are:

$LOCAL_MACHINE

$USERS

$CURRENT_USER

$CLASSES_ROOT

create( (out) $RegistryObj, $key );

$RegistryObj Reference to a registy object.

$key Name of a key.

If the key exists, then open it, otherwise create it. The User must have the security to create a key.

SetValue( $subkey,$type,$value );

$subkey Name of subkey

$type Type of value

$value Value

Set the value of the subkey of the current key to be $value.

QueryValue( (out)$value,(out)$type, $name );

(out)$value Value of var $name

(out)$type, Type of var $name

$name Name of value to query.

Sets $value, and $type for the specific name value in the current key.

QueryKey( (out)$class,(out)$NumberOfSubkeys, (out) NumberOfValues )

(out)$class Class of the key.

(out)$NumberOfSubkeys Number of subkeys of the current key.

(out) NumberOfValues Number of values in the current key.

Get the information from the current key.

GetKeys( (out) @Subkeys )

Return a list of character strings representing subkeys of the current key.

GetValues( (out)@Values )

Save( $filename );

Save registry from current location.

Load( $subkey,$filename );

Load a registry file.

Example

        
        use NT::Registry;
        
        $Hresult = $NT::HKEY_LOCAL_MACHINE->Open($NewObj,"MyKey");
        
        $NewObj->SetValue( "MySubKey",REG_SZ,5 );