ISyncChangeBatchBase2::SerializeWithOptions
Sérialise les données d'objet de lot de modifications en un tableau d'octets selon la version spécifiée et les options de sérialisation.
HRESULT SerializeWithOptions(
SYNC_SERIALIZATION_VERSION targetFormatVersion,
DWORD dwFlags,
BYTE * pbBuffer,
DWORD * pdwSerializedSize);
Paramètres
Terme |
Définition |
targetFormatVersion |
[in] Le lot de modifications sérialisé est compatible avec cette version. |
dwFlags |
[in] Réservé. Il doit s'agir de la valeur 0. |
pbBuffer |
[in, out, unique, size_is(*pdwSerializedSize)] Les données d'objet de lot de modifications sérialisé sont sérialisées en 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 mappage de clés de réplica lorsque pBuffer est trop petit, soit le nombre d'octets écrits. |
Valeur de retour
S_OK.
E_INVALIDARG lorsque la valeur dwFlags n'est pas 0, ou lorsque la version spécifiée par targetFormatVersion est incompatible avec les données d'objet de lot de modifications.
E_OUTOFMEMORY.
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_OPERATION lorsque le lot de modifications contient un groupe qui a été démarré mais qui n'a pas été terminé.
SYNC_E_INVALID_VERSION lorsque la valeur de targetFormatVersion est plus haute que 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 lot de modifications 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é quand l'objet de lot de modifications contient des éléments qui ne sont pas compatibles avec Sync Framework 1.0, E_INVALIDARG ou SYNC_E_INVALID_OPERATION est retourné.
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é.
Format de sérialisation
Le lot de modifications sérialisé contenu dans pbBuffer est stocké sous une forme compacte, sans remplissage, dans l'ordre d'octet avec primauté des octets de poids fort (big-endian). Le lot de modifications sérialisé 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 ULONGLONG
8
Version du format de sérialisation du lot de modifications. Cette valeur est 3 lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V1, 4 lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V2 et 5 lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V3.
Une section des informations de filtre lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V2 et les informations de filtre sont présentes dans le lot de modifications. La section des informations de filtre contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Longueur, en octets, de la section des informations de filtre.
Le reste de la section des informations de filtre est au format décrit dans ISyncFilterInfo::Serialize.
Une section de connaissance de destination. La section de connaissance de destination contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Longueur, en octets, de la section de connaissance de destination. Cette longueur peut être 0, auquel cas aucune connaissance de destination ne suit.
Séquence d'octets
Longueur spécifiée dans l'ULONG précédent.
Lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V1, la connaissance de destination est au format décrit par ISyncKnowledge::Serialize. Sinon, la connaissance de destination est au format décrit par ISyncKnowledge2::SerializeWithOptions. La connaissance de destination sérialisée contient toujours le mappage de clés de réplica sérialisé.
Une section de connaissance oubliée source. La section de connaissance oubliée source contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Longueur, en octets, de la section de connaissance oubliée source. Cette longueur peut être 0, auquel cas aucune connaissance oubliée source ne suit.
Séquence d'octets
Longueur spécifiée dans l'ULONG précédent.
Lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V1, la connaissance oubliée source est au format décrit par ISyncKnowledge::Serialize. Sinon, la connaissance oubliée source est au format décrit par ISyncKnowledge2::SerializeWithOptions. La connaissance oubliée source sérialisée contient toujours le mappage de clés de réplica sérialisé.
Section de mappage de clés de filtre source lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V3 et que les informations de mappage de clés de filtre source sont présentes. La section de mappage de clés de filtre source contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Longueur, en octets, de la section de mappage de clés de filtre source. Cette longueur peut être 0, auquel cas aucune mappage de clés de filtre source ne suit.
USHORT
2
Version du format de sérialisation du mappage de clés de filtre. Cette valeur est SYNC_SERIALIZATION_VERSION_V3.
ULONG
4
Nombre de filtres dans le mappage de clés de filtre.
Chaque filtre dans le mappage de clés de filtre contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Longueur, en octets, du filtre.
Séquence d'octets
Longueur spécifiée dans l'ULONG précédent.
Données de filtre sérialisées écrites dans le flux de données par la méthode ISyncFilter::Serialize.
Une section de connaissance courante. La section de connaissance courante contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Nombre d'objets de connaissance courante contenus dans les données sérialisées. Ce nombre peut être 0, auquel cas aucune connaissance courante ne suit.
Chaque connaissance courante contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Longueur, en octets, de la connaissance courante.
Séquence d'octets
Longueur spécifiée dans l'ULONG précédent.
Lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V1, la connaissance courante est au format décrit par ISyncKnowledge::Serialize. Sinon, la connaissance courante est au format décrit par ISyncKnowledge2::SerializeWithOptions. La connaissance courante sérialisée contient toujours le mappage de clés de réplica sérialisé.
Une section d'ensemble de modifications. La section d'ensemble de modifications contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Nombre d'objets de modification contenus dans les données sérialisées. Ce nombre peut être 0, auquel cas aucune modification ne suit.
Chaque modification contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Longueur, en octets, des données de modification.
ULONGLONG
8
Signature du format de sérialisation de l'objet de modification. Cette valeur est 5 lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V1 ou SYNC_SERIALIZATION_VERSION_V2 et 6 lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V3.
Lorsque les ID de réplica 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 de réplica.
ID de réplica de longueur fixe.
Ou, lorsque les ID de réplica 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 de réplica de longueur variable.
Chaque modification contient les éléments supplémentaires suivants.
Type de données Longueur en octets Description ULONG
4
Clé de réplica qui identifie le réplica à l'origine de cette modification.
ULONGLONG
8
Nombre de cycles pour le réplica à l'origine de cette modification.
ULONG
4
Réservé. Cette valeur peut être ignorée.
ULONGLONG
8
Réservé. Cette valeur peut être ignorée.
ULONG
4
Clé de réplica qui identifie le réplica qui a créé cet élément.
ULONGLONG
8
Nombre de cycles du réplica qui a créé cet élément.
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.
Lorsque targetFormatVersion est SYNC_SERIALIZATION_VERSION_V3 ou version ultérieure, chaque modification contient les éléments supplémentaires suivants.
Type de données Longueur en octets Description BOOL
1
Indique si un ID de gagnant existe dans les données sérialisées. La valeur 0 indique qu'aucun ID de gagnant ne suit. La valeur 1 indique qu'un ID de gagnant suit.
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 de gagnant 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 de gagnant de longueur variable.
Chaque modification contient les éléments supplémentaires suivants.
Type de données Longueur en octets Description ULONG
4
Indicateurs associés à la modification. Il s'agit d'une combinaison d'indicateurs SYNC_CHANGE_FLAG.
ULONG
4
Estimation du travail pour la modification.
USHORT
2
Réservé. Cette valeur est toujours 0.
BYTE
1
Indique si la connaissance acquise associée à cette modification est projetée sur cet élément. La valeur 0 indique que les connaissances acquises ne sont pas projetées. La valeur 1 indique que les connaissances acquises sont projetées.
ULONG
4
Index dans la liste de connaissances courantes contenue dans ces données sérialisées. Cette valeur peut être 0, qui indique qu'une connaissance courante n'est pas associée à cette modification.
ULONG
4
Nombre d'unités de modification contenues dans cette modification. Cette valeur peut être 0, auquel cas aucune unité de modification ne suit.
La modification contient une liste d'unités de modification, avec le nombre d'unités de modification égal à la valeur contenue dans l'ULONG précédent.
Chaque unité de modification 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 unité de modification contient les éléments supplémentaires suivants.
Type de données Longueur en octets Description ULONG
4
Clé de réplica qui identifie le réplica à l'origine de cette modification.
ULONGLONG
8
Nombre de cycles pour le réplica à l'origine de cette modification.
ULONG
4
Réservé. Cette valeur est toujours 0.
ULONGLONG
8
Réservé. Cette valeur est toujours 0.
Une section de synchronisation de récupération. La section de synchronisation de récupération contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
La longueur, en octets, de la section de synchronisation de récupération. Lorsque cette valeur est 0, aucune section de synchronisation de récupération ne suit.
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 représente la limite inférieure des modifications dans ce lot de modifications, lorsque le lot de modifications fait partie d'une synchronisation de récupération.
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 représente la limite inférieure des modifications dans ce lot de modifications, lorsque le lot de modifications fait partie d'une synchronisation de récupération.
Une section d'estimation du travail. La section d'estimation du travail contient les éléments suivants.
Type de données Longueur en octets Description ULONG
4
Estimation du travail de la session de synchronisation.
ULONG
4
Estimation du travail de ce lot de modifications.
Une section d'indicateurs. La section d'indicateurs contient les éléments suivants.
Type de données Longueur en octets Description BYTE
1
Indique si ce lot de modifications est le dernier lot de modifications envoyé par le fournisseur de source. La valeur 0 indique qu'il ne s'agit pas du dernier lot de modifications. La valeur 1 indique qu'il s'agit du dernier lot de modifications.
BYTE
1
Indique si ce lot de modifications fait partie d'une synchronisation de récupération. La valeur 0 indique que ce lot de modifications ne fait pas partie d'une synchronisation de récupération. La valeur 1 indique que ce lot de modifications fait partie d'une synchronisation de récupération.
BYTE
1
Indique si ce lot de modifications est filtré. La valeur 0 indique que ce lot de modifications n'est pas filtré. La valeur 1 indique que ce lot de modifications est filtré.