|
|
//--------------------------------------------------------------------
// 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 __cplusplus
extern "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_PASS
HRESULT 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_PASS
HRESULT 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_PASS
DWORD 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_PASS
DWORD 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_PASS
DWORD 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_PASS
DWORD 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_PASS
void 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__
|
