Creates, initializes, and saves new metadata for a replica.


HRESULT InitializeReplicaMetadata(
  BYTE * pbReplicaId,
  ID_PARAMETERS * pIdParameters,
  ULONG cItemCustomFields,
  CUSTOM_FIELDS_INDEX * pItemCustomFieldsIndexes,
  BYTE cItemCustomFieldsIndexes);


  • pbReplicaId
    [in] The replica ID for the replica that is represented by the metadata that is being created and initialized.

  • pIdParameters
    [in] The ID format schema for the provider.

  • pItemCustomFields
    [in, unique, size_is(cItemCustomFields)] The schema information that describes the custom metadata fields that are associated with the metadata items. Can be NULL if no custom metadata fields exist.

  • cItemCustomFields
    [in] The number of fields in pItemCustomFields.

  • pItemCustomFieldsIndexes
    [in, unique, size_is(cItemCustomFieldsIndexes)] The list of index schemas that can be used to more efficiently find items in the metadata store. Can be NULL if no index schemas exist.

  • cItemCustomFieldsIndexes
    [in] The number of indexes in pItemCustomFieldsIndexes.

Return Value

  • S_OK.



  • E_INVALIDARG if pItemCustomFields is NULL and cItemCustomFields is not 0, or if pItemCustomFields is non-NULL and cItemCustomFields is 0; or if the replica ID or the ID parameters are not valid; or if one of the custom fields specified by pItemCustomFields is not valid.

  • E_UNEXPECTED if the store is not yet open.

  • SYNC_E_METADATA_FIELD_INVALID_NAME when a field name specified in pItemCustomFieldsIndexes does not have a corresponding field specified in pItemCustomFields.

  • SYNC_E_METADATA_REPLICA_ALREADY_EXISTS when metadata already exists for the specified replica, such as when this method is called a second time.


The metadata store used by the metadata storage service implementation imposes certain restrictions on the custom fields. For more information, see CUSTOM_FIELD_DEFINITION Structure.

A set of custom fields can be defined for item metadata by using pItemCustomFields. Each field consists of a unique string name and a value. These fields can be used to store any additional metadata about an item that is not otherwise supported by the default set of item metadata. The fields can be accessed by using various methods on IItemMetadata, such as IItemMetadata::TryGetFieldByteArray or IItemMetadata::SetFieldByteArray.

A set of index schemas can be defined by using pItemCustomFieldsIndexes so that sets of custom fields can be used as indexes to efficiently find items in the metadata store. An index schema can be defined as unique to ensure that the index defines a single item. Each field that is contained in an index schema must also exist in the custom field schema that is defined for the replica. Index fields can be used in methods such as IReplicaMetadata::FindItemMetadataByIndexedFields and IReplicaMetadata::FindItemMetadataByUniqueIndexedFields.

See Also


ISyncMetadataStore Interface