Binaryworld - Working with NT EventLog - Part 3 (Implementing CEventLog Class, Writi ... [ VB -> WinNT ]

<< Previous Article | Next Article >>

In my previous article Working with NT EventLog - Part 2 (Implementing CEventLog Class, Creating Event Source) you learned how to use Registry API to create and delete Event Source and you also learned how to use OpenEventLog and CloseEventLog APIs. In this article I will Write operation with EventLog.

ReportEvent API is used to write a single entry to NT EventLog. This api has the following syntax.

Click here to copy the following block

Private Declare Function ReportEvent Lib "advapi32.dll" Alias "ReportEventA" ( _
    ByVal hEventLog As Long, _
    ByVal wType As Integer, _
    ByVal wCategory As Integer, _
    ByVal dwEventID As Long, _
    ByVal lpUserSid As Any, _
    ByVal wNumStrings As Integer, _
    ByVal dwDataSize As Long, _
    plpStrings As Long, _
    lpRawData As Any) As Boolean

Parameters

hEventLog : [in] Handle to the event log. This handle is returned by the RegisterEventSource function.
wType : [in] Specifies the type of event being logged. This parameter can be one of the following values.
EVENTLOG_SUCCESS
Success event
EVENTLOG_ERROR_TYPE
Error event
EVENTLOG_WARNING_TYPE
Warning event
EVENTLOG_INFORMATION_TYPE
Information event
EVENTLOG_AUDIT_SUCCESS
Success audit event
EVENTLOG_AUDIT_FAILURE
Failure audit event
wCategory : [in] Specifies the event category. This is source-specific information; the category can have any value.
dwEventID : [in] Specifies the event. The event identifier specifies the message that goes with this event as an entry in the message file associated with the event source.
lpUserSid : [in] Pointer to the current user's security identifier. This parameter can be NULL if the security identifier is not required.
wNumStrings : [in] Specifies the number of strings in the array pointed to by the lpStrings parameter. A value of zero indicates that no strings are present.
dwDataSize : [in] Specifies the number of bytes of event-specific raw (binary) data to write to the log. If this parameter is zero, no event-specific data is present.
lpStrings : [in] Pointer to a buffer containing an array of null-terminated strings that are merged into the message from the message file before Event Viewer displays the string to the user. This parameter must be a valid pointer (or NULL), even if wNumStrings is zero. Each string has a limit of 32K characters.
lpRawData : [in] Pointer to the buffer containing the binary data. This parameter must be a valid pointer (or NULL), even if the dwDataSize parameter is zero.

Here the most important parameter to understand is lpStrings which is pointer to array of null terminated string but in our case we have used pointer to array of pointers (string pointers). For example you have a message in your message file "Drive %1 has only %2 MB left, Please free some disk space". In this message you have 2 placeholders which you can replace with whatever you want. LogNTEvent function takes Array of strings which will be used to replace %1, %2..%n placeholders. From string array we will build array of pointers which points to null terminated strings.

Before you use ReportEvent API you have to call RegisterEventSource and when you done with reportEvent you can call DeregisterEventSource.

Click here to copy the following block

'//Note: RegisteredSource and RegisteredEventId both have to be registered in Messagefile
'//   check MSDN documentation for more info about how to Register your own Application
'//   as a event source so you can specify your application as a source
'//   If source,event or category any of this is not registered then you wont be able to
'//   see event Description of your log.

Public Function LogNTEvent(MsgToWrite As Variant, _
    Optional MachineName As String = "", _
    Optional LogType As enumLogEntryTypes = EVENTLOG_INFORMATION_TYPE, _
    Optional RegisteredSource As String = "Binaryworld", _
    Optional RegisteredEventID As Long = 1000, _
    Optional RegisteredCategoryID As Long = 0) As Boolean

  Dim retVal As Long, i As Integer
  Dim NumStrings As Integer
  Dim hEventLog As Long
  Dim strLogEntry As String
  Dim lgStringSize As Long
  Dim PtrArrayToStr() As Long

  '//If a single string is passed then convert it to Array variable
  If IsArray(MsgToWrite) = False Then MsgToWrite = Array(CStr(MsgToWrite))

  hRegisteredEventLog = RegisterEventSource(MachineName, RegisteredSource)

  On Error Resume Next
  NumStrings = UBound(MsgToWrite) + 1
  If Err.Number > 0 Then
    NumStrings = 1    '//In case no data is passed
    ReDim MsgToWrite(0)
    MsgToWrite(0) = ""
  End If
  On Error GoTo 0
  ReDim PtrArrayToStr(NumStrings - 1)

  '//Build an array of pointer to string (this strings are placeholders for %1,%2..%n in messages)
  For i = 0 To NumStrings - 1
    strLogEntry = MsgToWrite(i)
    lgStringSize = Len(strLogEntry) + 1 '//one extra byte for NULL char
    '//Allocate memory to hold string + Null char and store memory location in PtrArrayToStr(i)
    PtrArrayToStr(i) = GlobalAlloc(&H40, lgStringSize)
    '//Now copy strLogEntry to memory location stored in PtrArrayToStr(i)
    CopyMemory ByVal PtrArrayToStr(i), ByVal strLogEntry, lgStringSize
  Next

  retVal = ReportEvent(hRegisteredEventLog, _
      LogType, _
      RegisteredCategoryID, _
      RegisteredEventID, _
      0&, _
      NumStrings, _
      0, _
      PtrArrayToStr(0), _
      vbNullString)

  LogNTEvent = retVal

  For i = 0 To NumStrings - 1
    Call GlobalFree(PtrArrayToStr(i))
  Next

  Call DeregisterEventSource(hRegisteredEventLog)
End Function

Now in the next article I will show you how to read from event log.

Next Article : Working with NT EventLog - Part 4 (Implementing CEventLog Class, Reading from EventLog)

Previous Article : Working with NT EventLog - Part 2 (Implementing CEventLog Class, Creating Event Source)

<< Previous Article | Next Article >>