Microsoft Internet Security and Acceleration Server 2004 SDK

IFPCEventDefinition::Signal[C++]

FPCEventDefinition.Signal [Visual Basic]

[C++]

The Signal method signals the event on the local server. If an alert exists for the event and the conditions for issuing the alert are met, actions may be taken to notify the administrator of the event. Third-party filters can also use this method to signal an event.

HRESULT Signal(
  long SignalCount,
  long AdditionalKey,
  BSTR ShortDesc,
  BSTR LongDesc,
  long EventID,
  BSTR EventSource,
  VARIANT EventStrings,
  VARIANT EventData,
  short EventCategory,
  short EventType
);

Parameters

SignalCount
[in, optional] The number of instances of the event to be signaled. The default value is 1.
AdditionalKey
[in, optional] An additional key (index) from the table of subevents for the event. This parameter cannot be set to 0. The default value is –1.
ShortDesc
[in, optional] BSTR that provides a brief description of the run-time event. This description is used as the subject line of an e-mail message sent in a send-mail action. The default value is an empty string.
LongDesc
[in, optional] BSTR that provides a detailed description of the run-time event. This description is used as the body of an e-mail message sent in a send-mail action. The default value is an empty string.
EventID
[in, optional] A 32-bit integer that specifies the identifier (ID) of the event to be reported to the system event log. The default value is 0.
EventSource
[in, optional] BSTR that specifies the name of the software or application that should log the event. The default value is an empty string.
EventStrings
[in, optional] Variant that contains insertion strings for the event.
EventData
[in, optional] Variant that contains raw data for the event.
EventCategory
[in, optional] A 16-bit integer that specifies the category of the event. The default value is 0.
EventType
[in, optional] A 16-bit integer that specifies the type of the event. The default value is 0.

Return Values

This method returns S_OK if the call is successful; otherwise, it returns an error code.

Remarks

The EventSource parameter is similar to the lpSourceName parameter of the Windows RegisterEventSource function. Other parameters for this function are similar to parameters in the Windows ReportEvent function, as shown in the following table. For more information, see the relevant function in MSDN.

Signal parameter ReportEvent parameter
EventID dwEventID
EventStrings lpStrings
EventData lpRawData
EventCategory wCategory
EventType wType


Network data (including URLs and other data that comes from untrusted sources) should not be included in the EventStrings parameter for logging, because this can create a security risk. Such data, however, can be included in the RawData parameter for logging.

[Visual Basic]

The Signal method signals the event on the local server. If an alert exists for the event and the conditions for issuing the alert are met, actions may be taken to notify the administrator of the event. Third-party filters can also use this method to signal an event.

Sub Signal( _
  [ ByVal SignalCount As Long ], _
  [ ByVal AdditionalKey As Long ], _
  [ ByVal ShortDesc As String ], _
  [ ByVal LongDesc As String ], _
  [ ByVal EventID As Long ], _
  [ ByVal EventSource As String ], _
  [ ByVal EventStrings As Variant ], _
  [ ByVal EventData As Variant ], _
  [ ByVal EventCategory As Integer ], _
  [ ByVal EventType As Integer ] _
)

Parameters

SignalCount
[in, optional] The number of instances of the event to be signaled. The default value is 1.
AdditionalKey
[in, optional] An additional key (index) from the table of subevents for the event. This parameter cannot be set to 0. The default value is –1.
ShortDesc
[in, optional] String value that provides a brief description of the run-time event. This description is used as the subject line of an e-mail message sent in a send-mail action. The default value is an empty string.
LongDesc
[in, optional] String value that provides a detailed description of the run-time event. This description is used as the body of an e-mail message sent in a send-mail action. The default value is an empty string.
EventID
[in, optional] A 32-bit integer that specifies the identifier (ID) of the event to be reported to the system event log. The default value is 0.
EventSource
[in, optional] String value that specifies the name of the software or application that should log the event. The default value is an empty string.
EventStrings
[in, optional] Variant that contains insertion strings for the event.
EventData
[in, optional] Variant that contains raw data for the event.
EventCategory
[in, optional] A 16-bit integer that specifies the category of the event. The default value is 0.
EventType
[in, optional] A 16-bit integer that specifies the type of the event. The default value is 0.

Return Values

This method has no return values. If the call is unsuccessful, an error is raised that can be intercepted by using an error handler.

Remarks

The EventSource parameter is similar to the lpSourceName parameter of the Windows RegisterEventSource function. Other parameters for this function are similar to parameters in the Windows ReportEvent function, as shown in the following table. For more information, see the relevant function in MSDN.

Signal parameter ReportEvent parameter
EventID dwEventID
EventStrings lpStrings
EventData lpRawData
EventCategory wCategory
EventType wType


Network data (including URLs and other data that comes from untrusted sources) should not be included in the EventStrings parameter for logging, because this can create a security risk. Such data, however, can be included in the RawData parameter for logging.

Requirements

Server: Requires Windows Server 2003 or Windows 2000.
Version: Requires Internet Security and Acceleration Server 2004.
Header: Declared in Msfpccom.idl.
Library: Use Microsoft Internet Security and Acceleration Server 2004 Administration Library.

See Also

FPCEventDefinition