Sérialisation incrémentielle
Lorsque vous utilisez la sérialisation de style incrémentielle, vous fournissez trois routines pour manipuler la mémoire tampon. Ces routines sont : Alloc, Read et Write. La routine Alloc alloue une mémoire tampon de la taille requise. La routine d’écriture écrit les données dans la mémoire tampon, et la routine de lecture récupère une mémoire tampon qui contient des données marshalées. Un appel de sérialisation unique peut effectuer plusieurs appels à ces routines.
Le style incrémentiel de sérialisation utilise les routines suivantes :
- MesEncodeIncrementalHandleCreate
- MesDecodeIncrementalHandleCreate
- MesIncrementalHandleReset
- MesHandleFree
Les prototypes des fonctions Alloc, Read et Write que vous devez fournir sont indiqués ci-dessous :
void __RPC_USER Alloc (
void *State, /* application-defined pointer */
char **pBuffer, /* returns pointer to allocated buffer */
unsigned int *pSize); /* inputs requested bytes; outputs
/* pBuffer size */
void __RPC_USER Write (
void *State, /* application-defined pointer */
char *Buffer, /* buffer with serialized data */
unsigned int Size); /* number of bytes to write from Buffer */
void __RPC_USER Read (
void *State, /* application-defined pointer */
char **pBuffer, /* returned pointer to buffer with data */
unsigned int *pSize); /* number of bytes to read into pBuffer */
L’entrée d’état d’un paramètre pour les trois fonctions est le pointeur défini par l’application associé au handle des services d’encodage. L’application peut utiliser ce pointeur pour accéder à la structure contenant des informations spécifiques à l’application, telles qu’un handle de fichier ou un pointeur de flux. Notez que les stubs ne modifient pas le pointeur d’état autre que pour le transmettre aux fonctions Alloc, Read et Write. Lors de l’encodage, Alloc est appelé pour obtenir une mémoire tampon dans laquelle les données sont sérialisées. Ensuite, l’écriture est appelée pour permettre à l’application de contrôler quand et où les données sérialisées sont stockées. Pendant le décodage, read est appelé pour retourner le nombre demandé d’octets de données sérialisées à partir de laquelle l’application l’a stockée.
Une fonctionnalité importante du style incrémentiel est que le handle conserve le pointeur d’état pour vous. Ce pointeur conserve l’état et n’est jamais touché par les fonctions RPC, sauf lors du passage du pointeur à Alloc, Write ou Read function. Le handle gère également un état interne qui permet d’encoder et de décoder plusieurs instances de type dans la même mémoire tampon en ajoutant le remplissage si nécessaire pour l’alignement. La fonction MesIncrementalHandleReset réinitialise un handle à son état initial pour permettre la lecture ou l’écriture à partir du début de la mémoire tampon.
Les fonctions Alloc et Write, ainsi qu’un pointeur défini par l’application, sont associées à un handle de services d’encodage par un appel à la fonction MesEncodeIncrementalHandleCreate. MesEncodeIncrementalHandleCreate alloue la mémoire nécessaire pour le handle, puis l’initialise.
L’application peut appeler MesDecodeIncrementalHandleCreate pour créer un handle de décodage, MesIncrementalHandleReset pour réinitialiser le handle ou MesHandleFree pour libérer la mémoire du handle. La fonction Read, ainsi qu’un paramètre défini par l’application, est associée à un handle de décodage par un appel à la routine MesDecodeIncrementalHandleCreate. La fonction crée le handle et l’initialise.
Les paramètres UserState, Alloc, Write et Read de MesIncrementalHandleReset peuvent être NULL pour indiquer aucune modification.