AttachPropertyInstanceEx

The AttachPropertyInstanceEx function attaches a property to a frame, thus creating a PROPERTYINST and a PROPERTYINSTEX structure for that frame in the PROPERTYINSTTABLE for the frame.

DWORD AttachPropertyInstanceEx(
  HFRAME hFrame,        
  HPROPERTY hProperty,  
  DWORD Length,         
  LPVOID lpData,        
  DWORD LengthEx,       
  LPVOID lpDataEx,      
  DWORD HelpID,         
  DWORD IndentLevel,    
  DWORD IFlags          
);

Parameters

hFrame

Specifies the handle to the frame to which to add the property.

hProperty

Specifies the handle for the property to add.

Length

Specifies the length of the data in the frame in bytes. Length can be zero.

lpData

Specifies a pointer to the data in the frame where the Properties original value is located. lpData can be NULL.

LengthEx

Specifies the length of the extended data in bytes.

lpDataEx

Specifies a pointer to the extended data, usually a stack variable.

HelpID

Specifies a number (from 0 to 2047) signifying a Help identifier used to set context-sensitive Help on the property. The number is relative to the Help file identified with the property database identified in the CreatePropertyDatabase call.

IndentLevel

Specifies a number (from 0 to 15) signifying an indentation level for hierachical displays. Properties of type PROP_TYPE_SUMMARY should always be level 0. All other properties are the parser writer's prerogative, but starting at 1 will provide the most consistent display. The current user interface uses levels 0–9. Level 15 is a special level that allows the parser to attach a hidden property that will not normally be displayed.

IFlags

Specifies a bitfield that has the following definitions:

1	IFLAG_ERROR
2	IFLAG_SWAPPED (WORD or DWORD byte is non-Intel format at attach time)
4	IFLAG_UNICODE (STRING is UNICODE at attach time)

Note that earlier parsers set the fError DWORD to 0 or 1, which will map to IFLAG_ERROR.

Return Values

The return value is the error code.

Error code	Meaning
BHERR_SUCCESS	No problems were encountered.
BHERR_INVALID_HPROPERTY	The hProperty was invalid.
BHERR_INVALID_HFRAME	The hFrame was invalid.

Remarks

This function is used to attach a property to a frame, thus creating a PROPERTYINST and a PROPERTYINSTEX structure for that frame in the PROPERTYINSTTABLE for the frame. This function will add the information to the Frame as a PROPERTYINST structure.

The AttachPropertyInstanceEx function is used when data needs to be generated external to the frame data in order to more clearly describe the protocol. For example, the Ethernet parser generated a property that describes the length of the frame. Another example would be where the SMB parser converts the time to a SYSTEMTIME format and attaches the converted time with AttachPropertyInstanceEx so that the Generic Formatter will format it.

Note A copy of the lpDataEx structure is made (of LengthEx length) so that it can be in a temporary variable when calling this function. If the lpDataEx pointer is NULL, or the LengthEx parameter is zero, then the "ex" parameters will be ignored and AttachPropertyInstance will be called.