Method and mechanism for providing computer programs with computer system events6859829Abstract A method and system for providing system event notifications to clients such as applications. Clients register for notification of one or more types of events with a registration mechanism, and a System Event Notification Service, (SENS), receives system event information and fires event notifications in response thereto. A distribution mechanism selectively communicates the fired event to each client registered for notification thereof based on the type of event. Events include network events, for which the service monitors the connectivity state of the machine, including whether a connection is established or lost, the type of connection (LAN/WAN) and bandwidth information. To monitor a LAN state, the service caches outgoing and incoming network information including errors and packet counts and statistically evaluates this cached information against current information to determine whether the connection is established or lost. The service also determines if a destination (IP address or name) is reachable, by periodically polling destinations. Other system event notifications may be fired, including logon or logoff operations and power management events. Claims What is claimed is: Description COPYRIGHT NOTICE
Bool IsNetworkAlive(
LPDWORD lpdwFlags // Specifies the type of network connection
);
Parameters
lpdwFlags
Provides information on the type of network connection available
when the return value is TRUE. The flags can be:
NETWORK_ALIVE_LAN
the computer has one or more LAN cards that are active.
NETWORK_ALIVE_WAN
the computer has one or more active RAS connections.
Return Values
TRUE
The local system is connected to a network.
FALSE
Call GetLastError to determine the reason for no connectivity.
Remarks
This function is used by applications that want to know whether
there is network connectivity before proceeding with network
operations. Applications such as directory service applications, e-
mail clients, or Internet browsers can adapt to various kinds of
network connectivity. For example, a printing operation can be
deferred until the network connection is available. Note that at
present, this function is only available for TCP/IP connections.
Bool IsDestinationReachable(
LPCSTR lpszDesination, // Pointer to string specifying
destination
LPQOCINFO lpQOCInfo // Pointer to Quality of Connection
information
);
Parameters
lpszDestination
Pointer to a string that specifies the destination. The destination
can be an IP address, a UNC name, or an URL.
lpQOCInfo
Pointer to the QOCINFO structure that receives the Quality of
Connection (QOC) information. You can supply a NULL pointer if the
QOC information is not desired.
Return Values
TRUE
The destination can be reached.
FALSE
Call GetLastError to determine the reason why the destination cannot
be reached.
Remarks
This function is used by client applications to determine the QOC
information before proceeding with network operations. For
standalone computers that are directly connected to the network
through a network card or remote access server (RAS), this function
generates minimal network traffic with RPC calls to the nearest
router. For computers that are part of a network where the
destination can be reached using RAS or a network gateway, this
function pings to the destination to generate accurate QOC
information. Note that at present, this function is only available
for TCP/IP connections.
The caller supplies the buffer for the QOCINFO structure and must release this memory when it is no longer needed. The QOCINFO structure is returned by the IsDestinationReachable function and provides Quality of Connection information to the caller.
typedef struct tagQOCINFO {
DWORD dwSize;
DWORD dwFlags;
DWORD dwInSpeed;
DWORD dwOutSpeed;
} QOCINFO, *LPQOCINFO;
Members
dwSize
Upon calling the IsDestinationReachable function, the caller
supplies the size of the QOC structure in this member. On return
from the function, this member contains the actual size of the
structure that was filled in.
dwFlags
Speed of connection. Flag bits indicate whether the connection is
slow, medium, fast.
dwInSpeed
Speed of data coming in from the destination in bytes per second.
dwOutSpeed
Speed of data sent to the destination in bytes per second.
In accordance with another aspect of the present invention, another way in which a client (e.g., application) receives system events is by subscribing a sink object 80 or the like for notifications of events that interest it. As shown in FIG. 3, the subscriber application creates a sink object 80 with an implementation for each interface that it handles. The various types of events are generally categorized into appropriate interfaces, i.e., network-type events in one interface, power-type events in another interface, logon-type events in another interface and so on. FIG. 3 shows such a client subscriber sink object 80 set up to receive a relatively large number of SENS events, including network-type events via an ISensNetwork interface, power-type events via an ISensOnNow interface and logon-type events via an ISensLogon interface. Also, plug-and-play type events may be handled by the SENS 60, and although not presently -implemented, are shown herein to illustrate the extensibility of the present invention by simply adding additional interfaces such as ISensPnP with appropriate methods. Of course, a typical sink object ordinarily will not implement this many events, however FIG. 3 illustrates many of the possible events. The SENS 60 predefines an outgoing interface for each event class in a type library, as set forth in Table 1 below:
TABLE 1
Event
Class GUID Interface
Network SENSGUID_EVENTCLASS_NETWORK ISensNetwork
events
Logon SENSGUID_EVENTCLASS_LOGON ISensLogon
events
Power SENSGUID_EVENTCLASS_ONNOW ISensOnNow
events
The SENS 60 defines the SENS coclass as part of the SENS type library. The SENS object implementation is provided by the operating system, as set forth in Tables 2 and 3 below.
TABLE 2
Creation/Access Functions
CoCreateInstance Creates an instance of the SENS object
using its CLSID.
The ISensNetwork interface handles network events fired by the SENS 60. Each event corresponds to a method in the ISensNetwork interface, an outgoing interface defined by the SENS 60 and implemented by the subscriber application as a dispatch interface. The following table, Table 4, sets forth the methods of the ISensNetwork interface that correspond to network events:
TABLE 4
ISensNetwork Methods Description
ConnectionMade Specified connection has been
established.
ConnectionMadeNoQOCInfo Specified connection has been
established with no Quality of
Connection information available.
ConnectionLost Specified connection has been dropped.
DestinationReachable Specified connection can be reached.
DestinationReachableNoQ Specified connection can be reached with
OCInfo no Quality of Connection information.
Additional details on some of the methods of the ISensNetwork interface are set forth below:
ISensNetwork::ConnectionMade
The specified connection has been established.
HRESULT ConnectionMade(
BSTR bstrConnection, // Connection name
ULONG ulType, // Connection type
LPSENS_QOCINFO lpQOCInfo // Pointer to Quality of
// Connection information
);
Parameters
bstrConnection
[in] The name of the connection. For WAN connections, the
connection name is the name of the phone book entry; for LAN
connections, it is the name of the network card.
ulType
[in] Connection type. This value can be CONNECTION_LAN or
CONNECTION_WAN.
lpQOCInfo
[out] Pointer to the SENS QOCINFO structure which contains Quality
of Connection information.
Dispatch Identifier
[id(0x00000001)]
Return Values
S_OK
Method returned successfully.
Remarks -- SENS calls this method to notify an application that the
specified connection has been established. SENS also provides a
pointer to a structure containing Quality of Connection information.
Note that at present, this function is only available for TCP/IP connections.
SENS_QOCINFO Structure
The SENS_QOCINFO structure is provided by the
ISensNetwork::ConnectionMade method and the
ISensNetwork::DestinationReachable method. This structure contains
Quality of Connection information to the sink object in an
application that subscribes to the System Event Notification Service
(SENS).
typedef struct _SENS_QOCINFO {
DWORD dwSize;
DWORD dwFlags;
DWORD dwOutSpeed;
DWORD dwInSpeed;
} SENS_QOCINFO;
Members
dwSize
This member contains the actual size of the structure that was
filled in.
dwFlags
Speed of connection. Flag bits indicate whether the connection is
slow, medium, fast.
dwOutSpeed
Speed of data sent to the destination in bits per second.
dwInSpeed Speed of data coming in from the destination in bits per
second.
ISensNetwork::DestinationReachable
Directed to whether a specified connection can be reached.
HRESULT DestinationReachable(
BSTR bstrDesination, // Destination name
BSTR bstrConnection // Connection name
ULONG ultype // Connection type
LPSENS_QOCINFO lpQOCInfo // Quality of Connection
information
);
Parameters
bstrDestination
[in] Name of the destination. The name may be an IP address, a URL,
a UNC, or a NetBIOS name.
bstrConnection
[in] Name of the connection. For WAN connections, the connection
name is the name of the phone book entry; for LAN connections, it is
the name of the network card.
ulType
[in] Connection type. This value can be CONNECTION_LAN or
CONNECTION_WAN.
lpQOCInfo
[out] Pointer to the SENS_QOCINFO structure which contains Quality
of Connection information.
Dispatch Identifier
[id(0x00000004)]
Return Values
S_OK
Method returned successfully.
Remarks
SENS calls this method to notify an application that the specified
destination can be reached. A pointer to a structure containing
Quality of Connection information is also provided.
Note that at present, this function is only available for TCP/IP connections.
ISensNetwork::DestinationReachableNoQOCInfo
The specified connection can be reached with no Quality of
Connection information.
HRESULT DestinationReachableNoQOCInfo(
BSTR bstrDesination, // Destination name
BSTR bstrConnection, // Connection name
ULONG ultype // Connection type
);
Parameters
bstrDestination
[in] The name of the destination. Can be an IP address, a URL, a
UNC, or a NetBIOS name.
bstrConnection
[in] Name of the connection. For WAN connections, the connection
name is the name of the phone book entry; for LAN connections, it is
the name of the network card.
ulType
[in] Connection type. This value can be CONNECTION_LAN or
CONNECTION_WAN.
Dispatch Identifier
[id(0x00000005)]
Return Values
S_OK
Method returned successfully.
Remarks
SENS calls this method to notify an application that the specified
destination can be reached when Quality of Connection information is
not available.
Note that at present, this function is only available for TCP/IP connections. Several types of applications, for example, can utilize the connectivity functions and notification services that the SENS 60 offers. These include an application that requires network connectivity status, such as an application that utilizes directory services, or an application that adapts its operations depending on the level of connectivity and the quality of network services, such as an Internet browser that functions at a reduced level on a low bandwidth connection. Other applications that may benefit from this information include an application that can perform deferred operations, such as an electronic mail program that can queue messages while offline and send them when a connection is established. Connectivity functions and notifications are also useful for certain computer configurations, such as a mobile computer used in a docking station on a high bandwidth network which may occasionally use a dial-in connection, a mobile computer using a dial-in connection exclusively, a desktop computer using a dial-in connection exclusively or a desktop computer connected to a high bandwidth network with latency issues. In each of these configurations, the connection bandwidth and latency information can be used by an application to dynamically optimize its operations for network availability. As described above, LAN cards in general do not provide the appropriate LAN connectivity information needed to appropriately fire system events related thereto. However, in accordance with one aspect of the present invention, the SENS 60 provides a mechanism for detecting the network connectivity state, so that it can appropriately fire events in response to state changes. To this end, as shown in FIGS. 4 and 5, the SENS 60 caches network information in time-based caches 82.sub.T0 and 82.sub.T2. The cached information includes Unicast and non-Unicast incoming and outgoing network packet counts and incoming and outgoing error counts. These counts start at zero when the machine is last rebooted, and never decrease (until the next reboot). For each interface, this information is maintained as part of a TCP/IP stack 84 and made accessible through Internet Protocol Help (IPHLP) APIs 86. As described below, a snapshot is taken of the network information at two distinct times to fill the LAN caches 82.sub.T0 and 82.sub.T2, and the differences in counts evaluated by an evaluation mechanism 88 within the SENS 60 to determine network connectivity, i.e., whether the network is alive (true) or not (false). FIG. 6 shows the general process for determining network connectivity, beginning at step 600. One way to trigger the steps of FIG. 6 is when an application program 90 (FIG. 4) or the like calls the above-described IsNetworkAlive( ) API 91, requesting the network connectivity state information. Also, the SENS 60 can periodically check the state (e.g., once every two minutes) and appropriately fire events on state changes to registered clients. Certain other activities can also trigger the evaluation of network connectivity, as represented in FIG. 4 by ovals 92-95. These include plug and play events 92 directed to a LAN card, since plugging or unplugging such a card is likely to change the state of network connectivity. Similarly, certain network user interface activity 93, wherein a user can specifically ask to change the network connectivity state, may trigger a reevaluation. Remote Access Services (RAS) events 94 and Media Sense activity 95 can also trigger a reevaluation of network connectivity. Note that RAS may directly provide event information indicating whether a WAN connection is alive, which the SENS 60 then utilizes to fire events. Further, note that these other events essentially enter the reevaluation process at step 606, while the API call initially evaluates the last state by entering the process at step 600. Thus, when an API calls triggers the reevaluation, as an optimization, the network connectivity is not checked if it is alive (true) and has been checked recently, since networks do not fail often and evaluating the network information is relatively expensive. However, the network information is evaluated if false, or if one of the certain circumstances (described above) has taken place, since those events tend to happen when the network connectivity state changes, regardless of when last checked. If during the IsNetworkAlive( ) API call the network state was last determined to be true, step 600 branches to step 602 to test if the time duration, i.e., the current time minus the previous time T.sub.0, presently selected in one embodiment at 180 seconds, has been achieved since the last time connectivity was evaluated. If the duration is less than a threshold time, i.e., T.sub.1 <T.sub.0 +180, it is not yet time to check, whereby step 602 branches to step 604 where a "True" network state is returned. Alternatively, as shown in FIG. 6, if the network state is "False" (step 600) or if the time to check has been achieved (T.sub.2 >=T.sub.0 +180) at step 602, step 606 is next executed to fill a time-based cache 82.sub.T2 with network information at the current time, T.sub.2. Note that the first time, (since reboot), the state is assumed to be false, whereby an evaluation of the network information will take place. As described above and as represented in FIG. 5, each cache (e.g., 82.sub.T2) includes various packet and error counts. At step 606, the current cache 82.sub.T2 is evaluated against a previous cache 82.sub.T0 having the same count information therein, although current interfaces may have been added or removed since the time T.sub.0. Note that if the cache 82.sub.T0 at time T.sub.0 is too old or suspect, i.e., few if any of the interfaces are the same, the previous cache 82.sub.T0 can be scrapped, the current cache 82.sub.T2 can become the previous cache 82.sub.T0, and after (possibly) a short delay, new current counts can be obtained which become the values in the current cache 82.sub.T2. In any event, the values cached in the cache 82.sub.T2 are statistically evaluated against those in the cache 82.sub.T1 to determine if the network connectivity has changed. In general, if an incoming packet count has increased from time T.sub.2 to T.sub.0, and the errors are low, the network is alive, to a high degree of certainty. Conversely, if the outgoing packet counts have increased but the corresponding incoming counts have not relatively increased, the network is likely not alive. For example, to determine network connectivity, if unicastIN and unicastOUT have changed, the network is considered to be alive. Also, if unicastIN and unicastOUT have both not changed, AND broadcastIN and non-unicastOUT have changed by different amounts, the network is considered to be alive. However, if broadcastIN and non-unicastOUT have changed by the same amounts, it is just broadcast activity (e.g., the network tap has probably been pulled out), whereby the network is considered to be not alive. Moreover, if the Errors IN/OUT or discards IN/OUT have changed, the network is most likely alive and is thus considered as such. Once the state is determined, in the API call step 610 is executed top return the state as a result to the calling application. Step 612 is then executed to determine if the state has changed from its previous true or false value. If the state has changed, the SENS 60 fires the event, Network Alive (if True) or Network Not Alive (if false), to provide the current state via the Loosely Coupled Events database 70 to the clients registered therefor. Lastly, at step 616, this current state is maintained as the previous state and the current cache as the previous cache to be available for the next evaluation. In accordance with another aspect of the present invention, the SENS 60 also provides an event and/or API response as to whether a particular network destination is reachable. Applications can call the IsDestinationReachable( ) API or register for DestinationReachable change events. By way of example, rather than simply knowing whether the network is alive, an electronic mail program may-want to know whether its mail server is reachable. To this end, the electronic mail program calls the IsDestinationReachable( ) API or registers (typically at installation time) with the Loosely Coupled Events database 70 for "DestinationReachable" notifications, and provides the name of the mail server. The Loosely Coupled Events database 70 then informs the SENS 60, whereby the SENS 60 will find out and thereafter monitor this destination. The SENS 60 then fires events when the state of the mail server switches from reachable to not reachable and vice-versa. To determine destination reachability, the SENS 60 essentially executes the steps of FIG. 7, beginning at step 700 where a test is made as to whether the destination is named or is in the form of an IP address. If named, the SENS 60 attempts to resolve the name, i.e., by calling external TCP/IP name resolution APIs, and obtaining a result at step 702. If unable to be resolved, step 704 branches to step 706 where the "not reachable" result is returned to the calling program (if called as an API). A "Ping" cache 98 (FIG. 8) is updated at step 708 to reflect the unreachable state before branching to step 716, described below. If the IP address is known, either at step 700 or via steps 702-704, step 710 then tests to determine if the IP address corresponds to a local subnet (known from the value of the address). If so, then the destination is automatically considered reachable, and the reachable result is returned to the calling program (if called as an API) before branching to step 716, described below. Note that when a destination is considered reachable by the SENS 60, it is not a guarantee of reachability to an application. However local subnets are worth trying, and thus a "reachable" result is returned. If the IP address does not correspond to a local Subnet, at step 710, the destination may be pinged (i.e., a packet sent thereto) to see if it responds, whereby it is known whether it is reachable. However, rather than ping each time, the ping cache 98 may be maintained that keeps the reachable/unreachable states of one or more destinations therein. The ping cache 98 is regularly updated while the network is alive, for example, each destination in the ping cache 98 is pinged once every five minutes. The last pinged state for the appropriate destination is returned at step 714 to the application calling the API, although as can be appreciated, alternatively the API call can force the ping. Steps 716 and 718 cause an event to be fired to registered clients if a state change has occurred. For example, a name that previously was not resolvable is now resolved and it is in the local Subnet, or now responds when pinged, or a destination that formerly responded to pings no longer responds. Note that as also represented in FIG. 7, the ongoing monitoring process of the SENS 60 essentially pings each registered destination on a regular basis and then performs the steps 716-718 to determine whether to fire an event. A simple way in which to ping destinations is to keep a list of destinations and their corresponding reachable or unreachable states in the ping cache 98 as shown in FIG. 8. Then, a thread unblocks and executes once every time period (e.g., five minutes), and loops through the list by pulling each destination off of the list and essentially executing the steps of FIG. 7 therefor, writing any changed result into the ping table 98. The thread then blocks until again needed. However, while effective, the simple looping mechanism wastes a thread since most of the time the thread is idle while blocking. A more efficient way to perform the same pinging loop is to use thread pooling. In thread pooling, each executable is assigned a number of threads 100.sub.1 -100.sub.k, (e.g., three or four), plus a single thread (DLL) 102 which maintains a timer queue 104 of timed work items, one-time queued work items, and/or wait-based work items that wait on an event. At present, this provides the ability to wait on sixty-two objects with one thread 102. The SENS 60, using thread-pooling APIs 106, registers each destination to ping as a work item 102.sub.1 -102.sub.i with the operating system, along with any wait-based work items such as RAS connect and disconnect. The single thread 102 allocates one or more worker threads (e.g., 100.sub.1) to work items 102.sub.1 -102.sub.i in the queue 104 as appropriate, i.e., once every time period for ping work items, whereby the pinging operation takes place. When not pinging, threads may be thus allocated to other processes rather than blocking. In accordance with another aspect of the present invention, the SENS 60 provides notifications of AC and battery power events reported by the operating system 35. The ISensOnNow interface is implemented by clients interested in any of the SENS power events. As described above, this interface is an outgoing interface defined by SENS and implemented by the subscriber application as a dispatch interface. As also described above, when registering for battery low notifications, clients can specify filtering information. Each SENS power event corresponds to a method in the ISensOnNow interface, set forth below in Table 5:
TABLE 5
ISensOnNow Methods Description
OnACPower Switched to AC power.
OnBatteryPower Switched to Battery power.
BatteryLow Battery power is low.
Additional details for some of the methods of the
ISensOnNow interface are set forth below:
ISensOnNow::OnACPower
SENS calls this method to notify your application that the computer
is using AC power.
HRESULT OnACPower(void);
Dispatch Identifier
[id(0x00000001)]
Return Values
S_OK
Method returned successfully.
Remarks
SENS calls this method to notify an application that AC power has
been activated. If an application subscribes to this event, there
are no filters to specify.
ISensOnNow::OnBatteryPower
SENS calls this method to notify an application that the computer is
using battery power.
HRESULT OnBatteryPower(
DWORD dwBatteryLifePercent // Percent of battery power
remaining
);
Parameters
dwBatteryLifePercent
[in] Specifies the percent of battery power remaining.
Dispatch Identifier
[id(0x00000002)]
Return Values
S_OK
Method returned successfully.
Remarks
SENS calls this method to notify an application that the computer is
using battery power. The remaining percentage of battery power is
specified. If an application subscribes to this event, there are no
filters to specify.
The SENS 60 also handles additional notifications related to various system states via the ISensLogon interface. If any clients are interested, the SENS 60 centrally registers to find out about these events with the operating system/Winlogon service. The client application registers for these notifications and implements this ISensLogon interface as described above, whereby the SENS 60, via the Loosely Coupled Events database 70, calls the ISensLogon methods on the appropriately registered sink object to fire the corresponding event. The following table, Table 6, describes these events:
TABLE 6
ISensLogon Methods Description
Logon A user has logged on.
Logoff A user has logged off.
StartShell Shell has been started.
DisplayLock Screen display has been locked.
DisplayUnlock Screen display has been unlocked.
StartScreenSaver Screen saver has been started.
StopScreenSaver Screen saver has been stopped.
Lastly, the SENS 60 provides a special facility that may be used just before logoff, such as for synchronization purposes. As with logon, the SENS 60 registers with the operating system for certain event notifications. However, rather than after the event starts, when the SENS 60 receives the logoff indication, the SENS 60 fires a logoff event (if a client is registered for notification) and then delays the logoff process until a client that has registered for logoff notification instructs the SENS 60 to continue. This allows a client to perform pre-logoff processing after the user has requested logoff but before the actual logoff operation occurs. As can be seen from the foregoing detailed description, there is provided a centralized system event notification service that notifies registered clients of events. The method and system provide information such as network information that is otherwise unavailable or inconsistent in a consistent, efficient and extensible way. While the invention is susceptible to various modifications and alternative constructions, a certain illustrated embodiment thereof is shown in the drawings and has been described above in detail. It should be understood, however, that there is no intention to limit the invention to the specific form or forms disclosed, but on the contrary, the intention is to cover all modifications, alternative constructions, and equivalents falling within the spirit and scope of the invention.
|
Same subclass Same class Consider this |
||||||||||