ISyncMetadataStoreSerializer::DeserializeReplicaMetadata
Deserializes the contents of a canonical metadata file to a metadata storage service store. Optionally upgrades the metadata store format when the provider version changes.
HRESULT DeserializeReplicaMetadata(
IStream * pStream,
DWORD dwExpectedProviderCompatibilityVersion,
IProviderMetadataUpgradeCallback * pProviderUpgradeCallback);
Parameters
- pStream
[in] The stream that contains the serialized metadata for a particular replica.
- dwExpectedProviderCompatibilityVersion
[in] The provider compatibility version that is expected to be included in the canonical metadata file. If the expected version does not match the actual version, deserialization either fails by design when pProviderUpgradeCallback is NULL, or pProviderUpgradeCallback methods are called when pProviderUpgradeCallback is not NULL. For more information, see Accessing Metadata from Components with Different Versions and Upgrading the Metadata Store Version.
- pProviderUpgradeCallback
[in] Callback methods that are called when the metadata store format must be upgraded because the provider version contained in the serialized metadata is not the same as dwExpectedProviderCompatibilityVersion.
Return Value
S_OK.
S_FALSE if the highest tick count value in the serialized stream is less than or equal to the highest tick count value in the metadata store. In this case, there is no additional metadata to deserialize.
E_OUTOFMEMORY
E_POINTER
SYNC_E_INVALIDOPERATION if the method is called without an open metadata store.
SYNC_E_METADATA_ACTIVE_TRANSACTION_REQUIRED if a transaction is not available within which to deserialize metadata.
SYNC_E_METADATA_STORE_DESERIALIZATION_ERROR if any file format errors are encountered during deserialization or if the contents of the file are incompatible with the schema of the target replica.
SYNC_E_METADATA_STORE_DESERIALIZATION_PROVIDER_VERSION_MISMATCH if the provider compatibility version specified for dwExpectedProviderCompatibilityVersion does not match the version specified in the canonical metadata file and pProviderUpgradeCallback is NULL.
Remarks
Three conditions must be met before this method is called:
The metadata store must be opened. Open a store by calling ISqlSyncMetadataStore::OpenStore or ISqlSyncMetadataStore::CreateStore.
The replica for which data is deserialized must already have its metadata store initialized. To initialize a metadata store, call ISyncMetadataStore::InitializeReplicaMetadata.
An active transaction must be available on the ISqlSyncMetadataStore object. Start a transaction by calling ISyncMetadataStore::BeginTransaction.
Calling this method when any of these conditions is not met results in an error return value.
This method can be used as part of the procedure to upgrade the metadata schema when the provider version changes. For more information, see Upgrading the Metadata Store Version.