|
|
//--------------------------------------------------------------------// w32timep - interface//// Copyright (C) Microsoft Corporation, 2000//// Created by: Duncan Bryce (duncanb), 12-07-00//// Contains methods to configure or query the windows time service//
#ifndef __W32TIMEP_H__#define __W32TIMEP_H__ 1
#ifdef __cplusplusextern "C" {#endif
//-------------------------------------------------------------------------------------// Configurable / queryable properties for the windows time service://#ifndef MIDL_PASS#define W32TIME_CONFIG_SPECIAL_POLL_INTERVAL 0#define W32TIME_CONFIG_MANUAL_PEER_LIST 1#endif // MIDL_PASS
//-------------------------------------------------------------------------------------// W32TimeQueryConfig//// Queries configuration information for the windows time service. The semantics// of the parameters depend on which property is being query:// // dwProperty: W32TIME_CONFIG_SPECIAL_POLL_INTERVAL // pdwType: REG_DWORD // pbConfig: a DWORD-sized buffer, containing the special polling interval (in seconds).// The special polling interval can be specified as an alternative to // using the standard, automatically-computed polling intervals specified by// NTP. NOTE: The special polling interval applies only to microsoft time // providers.// pdwSize: sizeof(DWORD)// // // dwProperty: W32TIME_CONFIG_MANUAL_PEER_LIST// pdwType: REG_SZ// pbConfig: a space-delimited unicode string containing the list of time sources which the// microsoft time providers should sync from. Each is an IP address// or DNS name of an NTP server, optionally followed by a "flags" parameter.// For example: // // time.windows.com,0x3 gproxy,0x2 ntdsdc9//// The following flags are available:// // 0x1 -- use the special polling interval for this source, instead of the// standard NTP polling// 0x2 -- use this source only when no domain hierarchy sources are available//// pdwSize: sizeof(WCHAR) * (wcslen(pbConfig) + 1)//#ifndef MIDL_PASSHRESULT W32TimeQueryConfig(IN DWORD dwProperty, OUT DWORD *pdwType, IN OUT BYTE *pbConfig, IN OUT DWORD *pdwSize); #endif // MIDL_PASS
//-------------------------------------------------------------------------------------// W32TimeSetConfig//// Sets configuration information for the windows time service. The semantics// of the parameters depend on which property is being query. For a description // of the properties, see W32TimeQueryConfig(). // #ifndef MIDL_PASSHRESULT W32TimeSetConfig(IN DWORD dwProperty, IN DWORD dwType, IN BYTE *pbConfig, IN DWORD dwSize);#endif // MIDL_PASS
//-------------------------------------------------------------------------------------//// Client-side wrappers for the w32time RPC interface////-------------------------------------------------------------------------------------
#ifndef MIDL_PASS
#define TimeSyncFlag_SoftResync 0x00#define TimeSyncFlag_HardResync 0x01#define TimeSyncFlag_ReturnResult 0x02#define TimeSyncFlag_Rediscover 0x04#define TimeSyncFlag_UpdateAndResync 0x08
#define ResyncResult_Success 0x00#define ResyncResult_NoData 0x01#define ResyncResult_StaleData 0x02#define ResyncResult_Shutdown 0x03#define ResyncResult_ChangeTooBig 0x04
#endif // MIDL_PASS
//-------------------------------------------------------------------------------------// W32TimeSyncNow//// Sends an RPC request to the windows time service to attempt to synchronize time with// its configured time sources. //// wszServer: The name of the computer which should resync. // ulWaitFlag: if 0 is specified, the call will be asynchronous. Passing non-zero value// causes the call to block until time synchronization completes, or fails.// ulFlags: One of the resync types, or'd with any of the other flags. // NOTE: these flags are ignored by the Windows 2000 time service. Only// Windows XP and later servers will use them. //// Resync Types://// TimeSyncFlag_SoftResync -- the time service will synchronize the computer clock with// whatever time samples it currently has available. It will// not poll the network, or hardware providers, for more data. // TimeSyncFlag_HardResync -- tells the time service that a time slip has occured. // causing the time service will discard its time data. // Microsoft default providers will attempt to acquire more // network samples, if possible. // TimeSyncFlag_Rediscover -- tells the time service that it needs to re-resolve its// network sources, and attempt to acquire network time data. // //// Flags://// TimeSyncFlag_ReturnResult -- used only for asynchronous calls, causes the function// to return one of its possible return status codes, or an error.// See "Return Values".//// Return Values://// ResyncResult_Success -- indicates that the time synchronization has succeeded. For asynchronous// calls, this does not guarantee that the server has acquired more data, // merely that the request has been successfully dispatched. // ResyncResult_NoData -- Windows XP and later. For synchronous requests, or when the // TimeSyncFlag_ReturnResult is set, indicates that the time service couldn't// synchronize time because it failed to acquire time data. // ResyncResult_StaleData -- Windows XP and later. For synchronous requests, or when the // TimeSyncFlag_ReturnResult is set, indicates that the time service couldn't// synchronize time because the data it received was stale (time stamped// as received earlier than the last good sample)// ResyncResult_Shutdown -- Windows XP and later. For synchronous requests, or when the // TimeSyncFlag_ReturnResult is set, indicates that the time service couldn't// synchronize because the service was shutting down// ResyncResult_ChangeTooBig -- Windows XP and later. For synchronous requests, or when the // TimeSyncFlag_ReturnResult is set, indicates that the time service couldn't// synchronize because it would've required a change larger than that allowed// by the w32time policy//// Otherwise, the function returns a standard windows error.// #ifndef MIDL_PASSDWORD W32TimeSyncNow(IN const WCHAR *wszServer, IN unsigned long ulWaitFlag, IN unsigned long ulFlags);
#endif // MIDL_PASS
//-------------------------------------------------------------------------------------// W32TimeGetNetlogonServiceBits//// Queries the specified time service to determine what it advertises itself as in the// DS. //// wszServer: The name of the computer which should resync. // pulBits: A set of flags indicating what the specified time service is // advertised as. Can be the OR of the following values:// // DS_TIMESERV_FLAG: if the service is advertising as a time service// DS_GOOD_TIMESERV_FLAG: if the service is advertising as a reliable time service//// Return Values:// // ERROR_SUCCESS if the call succeeds, otherwise, the function returns a standard// windows error. //#ifndef MIDL_PASSDWORD W32TimeGetNetlogonServiceBits(IN const WCHAR *wszServer, OUT unsigned long *pulBits);#endif // MIDL_PASS
//--------------------------------------------------------------------------------//// NTP provider information structures////--------------------------------------------------------------------------------
// // W32TIME_NTP_PEER_INFO// // Represents the current state of a network provider's peer. //// Fields://// ulSize -- sizeof(W32TIME_NTP_PEER_INFO), used for versioning// ulResolveAttempts -- the number of times the NTP provider has attempted to // resolve this peer unsuccessfully. Setting this // value to 0 indicates that the peer has been successfully// resolved. // u64TimeRemaining -- the number of 100ns intervals until the provider will// poll this peer again// u64LastSuccessfulSync -- the number of 100ns intervals since (0h 1-Jan 1601) (in UTC). // ulLastSyncError -- S_OK if the last sync with this peer was successful, otherwise, // the error that occured attempting to sync// ulLastSyncErrorMsgId -- the resource identifier of a string representing the last// error that occured syncing from this peer. 0 if there is no// string associated with this error. The strings are stored in// the DLL in which this provider is implemented. // ulValidDataCount -- the number of valid samples from this peer the provider // currently has in its clock filter// ulAuthTypeMsgId -- the resource identifier of a string representing the // authentication mechanism used by the NTP provider to // secure communications with this peer. 0 if none. // The strings are stored in the DLL in which this // provider is implemented. // wszUniqueName -- a name uniquely identifying this peer (usually the peers// dns name). // ulMode -- one of the NTP modes specified in the NTPv3 spec://// +------------------+---+// | Reserved | 0 |// | SymmetricActive | 1 |// | SymmetricPassive | 2 |// | Client | 3 |// | Server | 4 |// | Broadcast | 5 |// | Control | 6 |// | PrivateUse | 7 |// +------------------+---+// // ulStratum -- this peer's stratum// ulreachability -- this peer's 1-byte reachability register. Each bit represents// whether or not a poll attempt returned valid data (set == success, // unset == failure). The low bit indicates the most recent sync, // the second bit represents the previous sync, etc. When this register// is 0, the peer is assumed to be unreachable. // ulPeerPollInterval -- the poll interval which this peer returned to the NTP provider (in log (base 2) seconds). // ulHostPollInterval -- the interval at which the NTP provider is polling this peer (in log (base 2) seconds). // typedef struct _W32TIME_NTP_PEER_INFO { unsigned __int32 ulSize; unsigned __int32 ulResolveAttempts; unsigned __int64 u64TimeRemaining; unsigned __int64 u64LastSuccessfulSync; unsigned __int32 ulLastSyncError; unsigned __int32 ulLastSyncErrorMsgId; unsigned __int32 ulValidDataCounter; unsigned __int32 ulAuthTypeMsgId; #ifdef MIDL_PASS [string, unique] wchar_t *wszUniqueName; #else // MIDL_PASS LPWSTR wszUniqueName;#endif // MIDL_PASS unsigned char ulMode; unsigned char ulStratum; unsigned char ulReachability; unsigned char ulPeerPollInterval; unsigned char ulHostPollInterval;} W32TIME_NTP_PEER_INFO, *PW32TIME_NTP_PEER_INFO;
//// W32TIME_NTP_PROVIDER_DATA//// Represents the state of an NTP provider.// // ulSize -- sizeof(W32TIME_NTP_PROVIDER_DATA), used for versioning// ulError -- S_OK if the provider is functioning correctly, // otherwise, the error which caused it to fail. // ulErrorMsgId -- the resource identifier of a string representing the// error that caused this provider to fail. // cPeerInfo -- the number of active peers used by this provider// pPeerInfo -- an array of W32TIME_NTP_PEER_INFO structures, representing // the active peers this provider is currently synchronizing with//typedef struct _W32TIME_NTP_PROVIDER_DATA { unsigned __int32 ulSize; unsigned __int32 ulError; unsigned __int32 ulErrorMsgId; unsigned __int32 cPeerInfo; #ifdef MIDL_PASS [size_is(cPeerInfo)]#endif // MIDL_PASS W32TIME_NTP_PEER_INFO *pPeerInfo; } W32TIME_NTP_PROVIDER_DATA, *PW32TIME_NTP_PROVIDER_DATA;
//--------------------------------------------------------------------------------//// HARDWARE provider structures////--------------------------------------------------------------------------------
// W32TIME_HARDWARE_PROVIDER_DATA//// Represents the state of a HARDWARE provider.// // ulSize -- sizeof(W32TIME_HARDWARE_PROVIDER_DATA), used for versioning// ulError -- S_OK if the provider is functioning correctly, // otherwise, the error which caused it to fail. // ulErrorMsgId -- the resource identifier of a string representing the// error that caused this provider to fail. // wszReferenceIdentifier -- the synchronization source (usually, the provider's// suggested 4-byte reference ID).// typedef struct _W32TIME_HARDWARE_PROVIDER_DATA { unsigned __int32 ulSize; unsigned __int32 ulError; unsigned __int32 ulErrorMsgId; #ifdef MIDL_PASS [string, unique] wchar_t *wszReferenceIdentifier; #else // MIDL_PASS LPWSTR wszReferenceIdentifier; #endif // MIDL_PASS } W32TIME_HARDWARE_PROVIDER_DATA, *PW32TIME_HARDWARE_PROVIDER_DATA;
//-------------------------------------------------------------------------------------// W32TimeQueryHardwareProviderStatus//// Queries the specified time service for information about one of its installed // time providers. // // wszServer: The name of the computer which should resync. // dwFlags: Reserved, must be 0. // pwszProvider: The name of the provider to query. // ppHardwareProviderData: A structure representing the current state of this hardware provider. // The returned buffer is allocated by the system, and should be// freed with W32TimeBufferFree(). // // Return Values:// // ERROR_SUCCESS if the call succeeds, otherwise, the function returns a standard// windows error. //#ifndef MIDL_PASSDWORD W32TimeQueryHardwareProviderStatus(IN const WCHAR *wszServer, IN DWORD dwFlags, IN LPWSTR pwszProvider, OUT W32TIME_HARDWARE_PROVIDER_DATA **ppHardwareProviderData);#endif // MIDL_PASS
//-------------------------------------------------------------------------------------// W32TimeQueryNTPProviderStatus//// Queries the specified time service for information about one of its installed // time providers. // // wszServer: The name of the computer which should resync. // dwFlags: Reserved, must be 0. // pwszProvider: The name of the provider to query. // ppNTPProviderData: A structure representing the current state of this hardware provider. // The returned buffer is allocated by the system, and should be// freed with W32TimeBufferFree(). // // Return Values:// // ERROR_SUCCESS if the call succeeds, otherwise, the function returns a standard// windows error. //#ifndef MIDL_PASSDWORD W32TimeQueryNTPProviderStatus(IN LPCWSTR pwszServer, IN DWORD dwFlags, IN LPWSTR pwszProvider, OUT W32TIME_NTP_PROVIDER_DATA **ppNTPProviderData); #endif // MIDL_PASS
//-------------------------------------------------------------------------------------// W32TimeBufferFree//// Frees a buffer allocated by the w32time client API. // // pvBuffer: the buffer to free.//#ifndef MIDL_PASSvoid W32TimeBufferFree(IN LPVOID pvBuffer); #endif // MIDL_PASS
////-------------------------------------------------------------------------------------
//-------------------------------------------------------------------------------------//// W32Time named events. // These events are ACL'd such that LocalSystem has full access. ////-------------------------------------------------------------------------------------
//// Signaling this event tells w32time that its time is off, causing the windows time// service to attempt resynchronization. This does not guarantee that the time service// will successfully adjust the system clock, or that resynchronization will occur// in a timely manner. // #define W32TIME_NAMED_EVENT_SYSTIME_NOT_CORRECT L"W32TIME_NAMED_EVENT_SYSTIME_NOT_CORRECT"
#ifdef __cplusplus} // balance extern "C" { #endif #endif // #ifndef __W32TIMEP_H__
|
