Microsoft SDK for Java

IJavaEventMonitorIDInfo3::
EnableMethodCallEvents

The EnableMethodCallEvents method of the IJavaEventMonitorIDInfo3 interface can be used to query the current settings, enable notification, or disable method notification callback events (MethodEntry, MethodExit, or MethodExit2 calls) for a specific method. The profiler or event monitor passes in an ID of the method or class that it is concerned with, an enumeration value that represents the type of the ID, and an enumeration that represents the disposition requested for this ID.

The EnableMethodCallEvents method is implemented only by the IJavaEventMonitorIDInfo3 interface.

Syntax

HRESULT EnableMethodCallEvents(ObjectID unique_id, JVM_ID_TYPE idtype, JVM_METHOD_CALL_EVENTS_DISPOSITION disposition);

Parameters

[in] unique_id The ClassID or MethodID that the profiler is interested in.
[in] idtype The type of the unique_id parameter, either a ClassID (JVM_ID_CLASS) or a MethodID (JVM_ID_METHOD).
[in] disposition The disposition requested for this ID.

Remarks

The profiler interfaces allow a profiler application to control whether method call events (notifications) are received on a global basis (for all method calls) or only for specific methods. To control method call events on a specific method, the profiler application must have set the bitmask for event type categories for which the Microsoft VM will the send event notifications to include the JVM_MONITOR_SPECIFIC_METHOD_CALLS value of the JAVA_EVENT_CATEGORY enumeration.

The disposition or request type can be any of the values defined in the JVM_METHOD_CALL_EVENTS_DISPOSITION enumeration.

JVM_METHOD_CALL_EVENTS_DISPOSITION

Constant Value Description
JVM_PROHIBIT_METHOD_CALL_EVENTS 1 Disable method call events for this ClassID or MethodID.
JVM_PERMIT_METHOD_CALL_EVENTS 2 Enable method call events for this ClassID or MethodID.
JVM_QUERY_DISPOSITION 3 Query the Microsoft VM on the status of method call events for this ClassID or MethodID.

The ID type passed to this method can be either value of the JVM_ID_TYPE enumeration.

JVM_ID_Type

Constant Value Description
JVM_ID_METHOD 5 A MethodID on which method call events will be enabled or disabled. A MethodID uniquely identifies a method.
JVM_ID_CLASS 7 A Class ID on which all method call events will be enabled or disabled. A ClassID uniquely identifies a class.

For example, if a ClassID is passed to EnableMethodCallEvents, the disposition (query, permit, or prohibit method call events) queries or modifies the behavior for all methods of this class.

The JVM_QUERY_DISPOSITION can be specified to determine the status of method call events. This method returns S_OK if the method will be notified (the method is hooked), S_FALSE if not, or E_FAIL if the method is already running. Hooking does not apply to the method, or hooking cannot be disabled for the method.

If the ID type is a JVM_ID_METHOD, the ObjectID passed to this method should be a MethodID. If the ID type is a JVM_ID_CLASS, the ObjectID passed should be a ClassID. The effect of using a ClassID is the same as enumerating all the MethodIDs of a class and invoking this function on each. In this case, the function returns S_OK if all the methods will be notified (hooked), S_FALSE if any of them will not or cannot be notified, or E_FAIL if none of them can be notified.

The final determination by the Microsoft VM to issue method call events on a class method is decided based on the following criteria: If any profiler has requested that a specific method not be hooked by specifying JVM_PROHIBIT_METHOD_CALL_EVENTS, no profilers or event monitors will receive callbacks for the method. The decision by a profiler to prohibit method call events on a method is irreversible. This feature is intended for use by a profiler to disable hooking of methods that are required to execute unobstructed for the proper functioning of the profiler (for example, a profiler that has Java-implemented methods that are invoked in response to a method call event).

If any profiler enables JVM_MONITOR_METHOD_CALLS, all methods (except those specifically prohibited by calls to EnableMethodCallEvents) will result in method call events being sent by the Microsoft VM to any profilers. Any profiler that has requested JVM_MONITOR_METHOD_CALLS or JVM_MONITOR_SPECIFIC_METHOD_CALLS will receive method call events for the method.

If any profiler turns on method call events for a specific set of methods by specifying JVM_PERMIT_METHOD_CALL_EVENTS, all profilers that have requested JVM_MONITOR_SPECIFIC_METHOD_CALLS will receive the events for the methods. If one profiler requests events for a specific method, all profilers will receive the events.

A profiler should not use JVM_PROHIBIT_METHOD_CALL_EVENTS to selectively disable method call events for a method. Instead, the profiler should request that no methods be hooked, and then enable hooking for those particular methods that are of interest. For example, a profiler could implement IJavaEventMonitorIDInfo2, but not return JVM_MONITOR_METHOD_CALLS from GetPossibleEventCategories, enable JVM_MONITOR_CLASS_LOADS, and at each JVM_EVENT_TYPE_CLASS_LOAD_FINISHED event, call EnableMethodCallEvents with JVM_PERMIT_METHOD_CALL_EVENTS to receive method call events for any methods that are interesting.

To prohibit or permit method call events, EnableMethodCallEvents must be called before the method has been executed. Currently, this function will fail if the method has already been executed; it should be called during the class load event for the method's class.

© 1999 Microsoft Corporation. All rights reserved. Terms of use.