ISyncKnowledge2::SerializeWithOptions
Sérialise les données d'objet de connaissance en un tableau d'octets selon la version spécifiée et les options de sérialisation.
Syntaxe
HRESULT SerializeWithOptions(
SYNC_SERIALIZATION_VERSION targetFormatVersion,
DWORD dwFlags,
BYTE* pBuffer,
DWORD* pdwSerializedSize);
Paramètres
Terme |
Définition |
targetFormatVersion |
[in] La connaissance sérialisée est compatible avec cette version. |
dwFlags |
[in] Options qui spécifient des informations supplémentaires sur la manière de sérialiser l'objet. Doit être 0 ou une combinaison des valeurs spécifiées par les indicateurs SYNC_SERIALIZE. Lorsque 0 est spécifié, le mappage de clés de réplica n'est pas inclus dans le cadre des données de connaissance sérialisées. |
pBuffer |
[in, out, unique, size_is(*pdwSerializedSize)] Les données sérialisées de l'objet de connaissance sont sérialisées dans cette mémoire tampon. |
pdwSerializedSize |
[in, out] Spécifie le nombre d'octets contenus dans pBuffer. Retourne soit le nombre d'octets requis pour sérialiser les données de connaissance lorsque pBuffer est trop petit, soit le nombre d'octets écrits. |
Valeur de retour
S_OK.
E_POINTER.
HRESULT_FROM_WIN32(ERROR_MORE_DATA) lorsque pBuffer est trop petit. Dans ce cas, le nombre requis d'octets est retourné dans pdwSerializedSize.
SYNC_E_INVALID_VERSION lorsque la valeur de targetFormatVersion est ultérieure à la version de l'objet, ou l'objet contient des éléments qui ne sont pas compatibles avec targetFormatVersion.
Notes
La valeur de targetFormatVersion détermine le format des données de connaissance sérialisées. Lorsque SYNC_SERIALIZATION_VERSION_V1 est spécifié, le format sérialisé est compatible avec Sync Framework 1.0 et les composants ultérieurs. Lorsque SYNC_SERIALIZATION_VERSION_V2 est spécifié, le format sérialisé est compatible avec les composants Sync Framework 2.0. Si SYNC_SERIALIZATION_VERSION_V2 est spécifié lorsque l'objet de connaissance contient des éléments qui ne sont pas compatibles avec Sync Framework 1.0, SYNC_E_INVALID_VERSION est retourné. Par exemple, la connaissance retournée par ISyncKnowledge2::ProjectOntoColumnSet contient des éléments introduits dans Sync Framework 2.0. Par conséquent, elle ne peut pas être sérialisée si SYNC_SERIALIZATION_VERSION_V1 est spécifié pour targetFormatVersion.
Notes
La sérialisation au format Sync Framework 1.0 est moins efficace qu'au format Sync Framework 2.0. À moins que le format Sync Framework 1.0 soit spécifiquement requis, le format Sync Framework 2.0 doit être utilisé.
L'objet Interface IReplicaKeyMap approprié est requis pour désérialiser un objet de connaissance en utilisant IProviderSyncServices::DeserializeSyncKnowledge. Lorsque SYNC_SERIALIZE_REPLICA_KEY_MAP est spécifié pour flags, l'objet IReplicaKeyMap est sérialisé avec les données de connaissance. Lorsque cet indicateur n'est pas spécifié, les données IReplicaKeyMap doivent être stockées d'une autre manière afin que l'objet de connaissance puisse être désérialisé.
Format de sérialisation
La connaissance sérialisée contenue dans pBuffer est stockée dans un format compact, sans remplissage, dans l'ordre d'octet avec primauté des octets de poids fort (big-endian).
Lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V1, la connaissance est sérialisée selon le format décrit dans ISyncKnowledge::Serialize. Sinon, la connaissance sérialisée contient les éléments ci-après, dans l'ordre suivant.
Une section d'en-tête. La section d'en-tête contient les éléments suivants :
Type de données
Longueur en octets
Description
ULONG
4
Version du format de sérialisation. Il s'agit de la valeur contenue dans targetFormatVersion ; elle doit être une valeur valide de l'énumération SYNC_SERIALIZATION_VERSION.
ULONG
4
Réservé. Cette valeur est toujours 0.
ULONG
4
Version minimale prise en charge de la connaissance sérialisée.
ULONG
4
Réservé. Cette valeur est toujours 0.
Une section de mappage de clés de réplica lorsque dwFlags contient SYNC_SERIALIZE_REPLICA_KEY_MAP. Sinon, aucune section de mappage de clés de réplica n'est présente. Le format de la section de mappage de clés de réplica est défini dans IReplicaKeyMap::Serialize.
Signature qui indique le jeu suivant de sections :
Type de données
Longueur en octets
Description
ULONG
4
Signature de la section. Cette valeur est toujours 24.
Une section de schéma de format d'ID. La section de schéma de format d'ID contient les éléments suivants :
Type de données
Longueur en octets
Description
BOOL
1
Indique si les ID de réplica contenus dans la connaissance sont de longueur fixe ou variable. Cette valeur est 0 si les ID sont de longueur fixe ou 1 si les ID sont de longueur variable.
USHORT
2
Longueur, en octets, des ID de réplica pour les ID de longueur fixe, ou la longueur maximale de l'ID pour les ID de longueur variable.
BOOL
1
Indique si les ID d'élément contenus dans la connaissance sont de longueur fixe ou variable. Cette valeur est 0 si les ID sont de longueur fixe ou 1 si les ID sont de longueur variable.
USHORT
2
Longueur, en octets, des ID d'élément pour les ID de longueur fixe, ou la longueur maximale de l'ID pour les ID de longueur variable.
BOOL
1
Indique si les ID d'unité de modification contenus dans la connaissance sont de longueur fixe ou de longueur variable. Cette valeur est 0 si les ID sont de longueur fixe ou 1 si les ID sont de longueur variable.
USHORT
2
Longueur, en octets, des ID d'unité de modification pour les ID de longueur fixe, ou la longueur maximale de l'ID pour les ID de longueur variable.
Une section de table de vecteur horloge. La section de table de vecteur horloge contient les éléments suivants :
Type de données
Longueur en octets
Description
ULONG
4
Signature de la table de vecteurs horloge. Cette valeur est toujours 21.
ULONG
4
Nombre de vecteurs horloge contenus dans la table de vecteurs horloge.
La table de vecteurs horloge contient une liste de vecteurs horloge, avec le nombre de vecteurs horloge égal à la valeur spécifiée dans l'ULONG précédent. Chaque vecteur horloge contient les éléments suivants :
Type de données
Longueur en octets
Description
ULONG
4
Signature du vecteur horloge. Cette valeur est 1 lorsque le vecteur horloge ne contient pas d'éléments de flux FeedSync ; dans le cas contraire, la valeur est 9.
ULONG
4
Nombre d'éléments de vecteur horloge contenus dans ce vecteur horloge.
Lorsque le vecteur horloge contient des éléments de flux FeedSync, la section suivante existe dans la connaissance sérialisée ; sinon, elle n'existe pas :
Type de données
Longueur en octets
Description
ULONG
4
Nombre de mises à jour apportées au flux FeedSync qui est associé à cette connaissance. Cette valeur correspond à l'attribut updates du flux FeedSync.
BYTE
1
Indique si le flux FeedSync effectue le suivi des conflits. Cette valeur correspond à l'attribut noconflicts du flux FeedSync. Cette valeur est 0 lorsque noconflicts n'est pas défini ; sinon, la valeur est 1.
Le reste du vecteur horloge contient la liste des éléments de vecteur horloge, avec le nombre d'éléments égal à la valeur spécifiée précédemment dans la section de vecteur horloge.
Chaque élément de vecteur horloge contient les éléments suivants :
Type de données
Longueur en octets
Description
ULONG
4
Clé de réplica.
ULONGLONG
8
Nombre de cycles.
Lorsque la connaissance est associée à un flux FeedSync, chaque élément de vecteur horloge contient les éléments supplémentaires suivants :
Type de données
Longueur en octets
Description
ULONG
4
Partie date de la valeur when du flux FeedSync.
ULONG
4
Partie heure de la valeur when du flux FeedSync.
BYTE
1
Indicateurs associés au flux FeedSync.
Une section de jeu de plages. La section de jeu de plages contient les éléments suivants :
Type de données
Longueur en octets
Description
ULONG
4
Signature de la section de jeu de plages. Cette valeur est toujours 23.
ULONG
4
Nombre de jeux de plages inclus de cette section.
La section de jeu de plages contient une liste de jeux de plages, avec le nombre de jeux de plages égal à la valeur spécifiée dans l'ULONG précédent. Le premier jeu de plages est le jeu de plages d'étendues.
Chaque jeu de plages contient les éléments suivants :
Type de données
Longueur en octets
Description
ULONG
4
Signature de jeu de plages. Cette valeur est toujours 22.
ULONG
4
Nombre de plages incluses dans ce jeu de plages.
Chaque plage dans le jeu de plages contient les éléments suivants :
Lorsque les ID d'élément sont de longueur fixe :
Type de données
Longueur en octets
Description
Séquence d'octets
Longueur spécifiée dans le format d'ID d'élément.
ID d'élément de longueur fixe qui commence la plage.
Ou, lorsque les ID d'élément sont de longueur variable :
Type de données
Longueur en octets
Description
USHORT
2
Longueur, en octets, de l'ID de longueur variable. Cette longueur inclut les deux octets pour l'USHORT qui contient la longueur, plus les octets qui contiennent l'ID réel.
Séquence d'octets
Longueur spécifiée dans l'USHORT précédent.
ID d'élément de longueur variable qui commence la plage.
Chaque plage contient l'élément supplémentaire suivant :
Type de données
Longueur en octets
Description
ULONG
4
Index dans la table de vecteurs horloge contenue dans ces données sérialisées.
Une section de jeu de colonnes. La section de jeu de colonnes contient les éléments suivants :
Type de données
Longueur en octets
Description
ULONG
4
Nombre de colonnes incluses dans cette section.
Chaque colonne dans la section de jeu de colonnes contient les éléments suivants :
Lorsque les ID d'unité de modification sont de longueur fixe :
Type de données
Longueur en octets
Description
Séquence d'octets
Longueur spécifiée dans le format des ID d'unité de modification.
ID d'unité de modification de longueur fixe.
Ou, lorsque les ID d'unité de modification sont de longueur variable :
Type de données
Longueur en octets
Description
USHORT
2
Longueur, en octets, de l'ID de longueur variable. Cette longueur inclut les deux octets pour l'USHORT qui contient la longueur, plus les octets qui contiennent l'ID réel.
Séquence d'octets
Longueur spécifiée dans l'USHORT précédent.
ID d'unité de modification de longueur variable.
Chaque colonne dans la section de jeu de colonnes contient l'élément supplémentaire suivant :
Type de données
Longueur en octets
Description
ULONG
4
Index dans la section de jeu de plages contenue dans ces données sérialisées.
Lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V3 ou une version ultérieure, les données sérialisées contiennent une section de jeu de marqueurs. La section de jeu de marqueurs contient les éléments suivants :
Type de données
Longueur en octets
Description
ULONG
4
Signature de la section de jeu de marqueurs. Cette valeur est toujours 25.
BOOL
1
Indique si les éléments répertoriés dans cette section contiennent ou requièrent toutes les unités de modification. Cette valeur est 0 lorsque des unités de modification sont présentes, ou 1 lorsque des unités de modification sont requises. Un seul de ces types de marqueur peut être présent.
ULONG
4
Nombre d'ID d'éléments répertoriés dans cette section.
La section de jeu de marqueurs contient une liste d'ID d'élément, avec le nombre d'ID égal à la valeur contenue dans l'ULONG précédent.
Chaque ID d'élément contient les éléments suivants :
Lorsque les ID d'élément sont de longueur fixe :
Type de données
Longueur en octets
Description
Séquence d'octets
Longueur spécifiée dans le format d'ID d'élément.
ID d'élément de longueur fixe.
Ou, lorsque les ID d'élément sont de longueur variable :
Type de données
Longueur en octets
Description
USHORT
2
Longueur, en octets, de l'ID de longueur variable. Cette longueur inclut les deux octets pour l'USHORT qui contient la longueur, plus les octets qui contiennent l'ID réel.
Séquence d'octets
Longueur spécifiée dans l'USHORT précédent.
ID d'élément de longueur variable.