3.2.5.3 W32TimeQueryProviderStatus (Opnum 2)

  • Article

The W32TimeQueryProviderStatus method returns operational information for a specified time provider (either an NTP or a hardware time provider) within the time service's list of time providers.<39> The MIDL syntax of this method is specified as follows.

 unsigned long W32TimeQueryProviderStatus(
   [in] handle_t hRPCBinding,
   [in] unsigned __int32 ulFlags,
   [in, string] wchar_t* pwszProvider,
   [out, ref] PW32TIME_PROVIDER_INFO* pProviderInfo
 );

hRPCBinding: RPC primitive binding handle as specified in [C706] part 3, sections Interface Definition Language and Stubs.

ulFlags: Reserved. This parameter MUST be set to zero and MUST be ignored on receipt.

pwszProvider: Name of the time provider to query. This name is implementation specific.<40>

pProviderInfo: A pointer that receives a pointer to a W32TIME_PROVIDER_INFO structure containing operational information for the time provider.

Return Values: This method MUST return zero on success; on failure, it returns a nonzero error code. The values transmitted in this field are implementation specific. All nonzero values MUST be treated as equivalent for protocol purposes.<41>

When W32TimeQueryProviderStatus is invoked, the server SHOULD examine its TimeProviderList to locate the time provider corresponding to the name pwszProvider. If the provider cannot be located, the server MUST return ERROR_NOT_FOUND, as specified in [MS-ERREF]; otherwise, the server MUST return the associated time provider information structure, as specified in section 2.2.1, and populate it as follows:

  1. pProviderInfo.ulProviderType MUST be set to 0.

  2. pProviderInfo.ProviderData.pNtpProviderData.ulSize MUST be set with the size, in bytes, of the W32TIME_NTP_PROVIDER_DATA structure.

  3. pProviderInfo.ProviderData.pNtpProviderData.ulError MUST be set to zero if the NTP time provider is functioning correctly; otherwise, it MUST be set to an implementation-specific nonzero unsigned integer value.

  4. pProviderInfo.ProviderData.pNtpProviderData.ulErrorMsgId MUST be set to an implementation-specific positive integer value that maps to a human-readable message that describes the failure indicated in the pProviderInfo.ProviderData.pNtpProviderData.ulError field.

  5. pProviderInfo.ProviderData.pNtpProviderData.cPeerInfo MUST be the count of active time peers that synchronize with this NTP time provider.

  6. For each active time peer to return, the server MUST fill an element in the pProviderInfo.ProviderData.pNtpProviderData.pPeerInfo field according to the following table.

    Element field

    Value

    ulSize

    The size, in bytes, of the W32TIME_NTP_PEER_INFO structure.

    ulResolveAttempts

    The ResolvedAttempts element value (see section 3.2.1.3)

    u64TimeRemaining

    The TimeRemaining element value (see section 3.2.1.3)

    u64LastSuccessfulSync

    The LastSuccessfulSync element value (see section 3.2.1.3)

    ulLastSyncError

    The LastSyncError element value (see section 3.2.1.3)

    ulLastSyncErrorMsgId

    The LastSyncErrorMessageId element value (see section 3.2.1.3)

    ulValidDataCounter

    The ValidDataCounter element value (see section 3.2.1.3)

    ulAuthTypeMsgId

    The AuthenticationTypeMessageId element value (see section 3.2.1.3)

    wszUniqueName

    The PeerName element value (see section 3.2.1.3)

    ulMode

    The current NTP association mode (peer.mode), as specified in [RFC1305] section 3.2.1, "Common Variables".

    ulStratum

    The stratum (peer.stratum), as specified in [RFC1305] section 3.2.3, "Peer Variables".

    ulReachability

    The reachability register (peer.reach), as specified in [RFC1305] section 3.2.3, "Peer Variables".

    ulPeerPollInterval

    The Peer Poll Interval (peer.peerpoll), as specified in [RFC1305] section 3.2.3, "Peer Variables".

    ulHostPollInterval

    The Host Poll Interval (peer.hostpoll), as specified in [RFC1305] section 3.2.3, "Peer Variables".