3.1.5.4.1 GetReport Method (Opnum 3)

  • Article

The GetReport method retrieves health information for the specified replication group that is hosted on the server in addition to the global health data of the DFS-R service on the server.

 HRESULT GetReport(
   [in] GUID replicationGroupGuid,
   [in] BSTR referenceMember,
   [in] SAFEARRAY (_VersionVectorData)* referenceVersionVectors,
   [in] long flags,
   [out] SAFEARRAY (_VersionVectorData)* memberVersionVectors,
   [out] BSTR* reportXML
 );

replicationGroupGuid: MUST be the identifier of the replication group for which the server gets health information. This field corresponds to the objectGUID field of the msDFSR-ReplicationGroup configuration object in Active Directory. The msDFSR-ReplicationGroup is specified in [MS-FRS2] section 2.3.5.

referenceMember: MUST be set to NULL.

referenceVersionVectors: If the flags parameter has REPORTING_FLAGS_BACKLOG set, the set of version vectors for replicated folders on the reference member MUST be passed by using this parameter. Otherwise, this parameter MUST be set to NULL. The VersionVectorData structure is specified in section 2.2.1.4.

flags: Any values of the DfsrReportingFlags enumeration MUST be combined together by using a bitwise OR operation. For more information about DfsrReportingFlags, see section 2.2.1.2.

Value

Meaning

REPORTING_FLAGS_NONE

When this value is set, the server MUST NOT return any optional information.

REPORTING_FLAGS_BACKLOG

In addition to the default reporting information, when this value is set, the server MUST return the count of backlogged transactions.

REPORTING_FLAGS_FILES

In addition to the default reporting information, when this value is set, the server MUST return the information about the count and cumulative size of files in the replicated folders.

memberVersionVectors: If the flags parameter has REPORTING_FLAGS_BACKLOG set, the set of version vectors for the replicated folders on the server MUST be returned in this output parameter. The VersionVectorData structure is specified in section 2.2.1.4.

reportXML: The report body in the XML format MUST be returned in this output parameter. The report body MUST follow the XML format described in section 2.2.1.5.

Return Values: The method MUST return 0 on success; or return an implementation-specific nonzero HRESULT error code, as specified in [MS-ERREF] section 2.1, between 0x80000000 and 0xFFFFFFFF on failure. For protocol purposes, all nonzero values MUST be treated as equivalent failures.

After receiving this message, the server MUST validate only the following parameters:

  • Verify that the reportXML pointer is not NULL.

If validation of the reportXML parameter fails, the server MUST fail the operation immediately and return an appropriate error as its response to the client.<58>

If the REPORTING_FLAGS_BACKLOG flag was set in the flags parameter, the server MUST get the member version vector for each enabled replicated folder in the replication group with the GUID that is specified by the replicationGroupGuid parameter. The server MUST save information about the version vectors in the memberVersionVectors output parameter.

The server MUST also generate report XML. The server MUST get the following information (for more information, see section 2.2.1.5):

  • Information about the configuration of the replicated folder (replicated folder root path, staging folder path, conflict folder path, and configured staging size).

  • Information about files that were received from other DFS-R members since the DFS-R service started, which SHOULD occur when the system is booted. The required information is the count and cumulative compressed size of the files received, as well as the cumulative compressed size of the files received from other members.

  • Information about available errors that were encountered by the DFS-R service since the server started, as well as errors encountered during report generation while retrieving information about the replication group supplied by the replicationGroupGuid parameter. These errors are specified in section 2.2.1.5.17.

  • If the REPORTING_FLAGS_BACKLOG flag was specified in message parameters, the server MUST also get the count of pending incoming changes that are known to the reference member (as specified by the version vectors passed in the method parameters) but that are not yet received on the local member.

  • If the REPORTING_FLAGS_FILES flag was specified in message parameters, the server MUST also count the number of files and cumulative file sizes for:

    • Files under the replicated folder root that are available for replication. The server MUST NOT count any files that are excluded from replication.

    • Files in the conflict folder.

    • Files in the staging folder. For the staging folder, the server MUST count only the cumulative size of the files and specify -1 instead of the count of files.

If an error is encountered while the server is getting this information, the server SHOULD choose to proceed with getting other health information and to exclude from the report the information that it was unable to collect.  Alternatively, the server MAY choose to abort further processing and return the implementation-specific error to the client. <59>