From 839b5b258cee48b574da271034679ba3f2565473 Mon Sep 17 00:00:00 2001 From: Michael Mann Date: Sun, 9 Mar 2014 11:02:30 +0100 Subject: [PATCH] Update documentation about p_[add|get]_proto_data (new argument: scope) Change-Id: Ic27b0e601967c90567fac58447d28b10c02a3888 Reviewed-on: https://code.wireshark.org/review/564 Reviewed-by: Alexis La Goutte Tested-by: Alexis La Goutte Reviewed-by: Anders Broman --- doc/README.dissector | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/doc/README.dissector b/doc/README.dissector index ae6980e464..a693284381 100644 --- a/doc/README.dissector +++ b/doc/README.dissector @@ -2645,16 +2645,22 @@ static dissector_handle_t sub_dissector_handle; Information can be stored for each data packet that is processed by the dissector. The information is added with the p_add_proto_data function and retrieved with the p_get_proto_data function. The data pointers passed into -the p_add_proto_data are not managed by the proto_data routines. If you use -malloc or any other dynamic memory allocation scheme, you must release the -data when it isn't required. +the p_add_proto_data are not managed by the proto_data routines, however the +data pointer memory scope must match that of the scope parameter. +The two most common use cases for p_add_proto_data/p_get_proto_data are for +persistent data about the packet for the lifetime of the capture (file scope) +and to exchange data between dissectors across a single packet (packet scope). +It is also used to provide packet data for Decode As dialog (packet scope). void -p_add_proto_data(frame_data *fd, int proto, void *proto_data) +p_add_proto_data(wmem_allocator_t *scope, frame_data *fd, int proto, void *proto_data) void * -p_get_proto_data(frame_data *fd, int proto) +p_get_proto_data(wmem_allocator_t *scope, frame_data *fd, int proto) Where: + scope - Lifetime of the data to be stored, typically wmem_file_scope() + or pinfo->pool (packet scope). Must match scope of data + allocated. fd - The fd pointer in the pinfo structure, pinfo->fd proto - Protocol id returned by the proto_register_protocol call during initialization