Property Values

A property structure often contains three types of properties: IN properties, OUT properties, and IN/OUT properties.

• IN properties use values set by the application. They are passed to MSMQ as IN parameters and can either identify or set queue or message properties. For example, the application must supply the MSMQ pathname for the queue when the queue is created.
• OUT properties use values set by MSMQ. For example, when a queue is created, MSMQ sets the time when it was created.
• IN/OUT properties initially use values passed to MSMQ, and then MSMQ resets the value when the property is passed back to the application. For example, when the receiving application asks for the destination queue of a message, it must first tell MSMQ the size of the buffer allocated for the destination queue's format name. On return, MSMQ passes back the actual size of the format name.

Properties appear in no particular order in the aPropVar array. To determine the type of a property, MSMQ examines the property identifier and the function called. For example, for API functions, the queue quota property (PROPID_Q_QUOTA) is an OUT property when MQGetQueueProperties is called and an IN property when MQSetQueueProperties is called.

IN properties can be set to any valid setting for the specific property. However, VT_NULL cannot be used as an IN property VARTYPE value.

OUT properties returned by MSMQ require a PROPVARIANT entry where the returned value can be stored. For example, space must be allocated before the label of a queue or the body of a message can be specified. There are two ways for the application to specify such a PROPVARIANT entry:

• Prepare a PROPVARIANT entry with the appropriate VARTYPE value (vt field) for the expected value, allocating the corresponding buffer when appropriate. For example, if a message body is specified, allocate the array of bytes to be pointed to by the caui1.pElems field.
• Let MSMQ fill in the PROPVARIANT with the appropriate VARTYPE value. To do this, set the vt field to VT_NULL. If memory is required, MSMQ allocates the buffer for the field as long as its value is stored in the PROPVARIANT structure (for example, VT_LPWSTR).

  For example, if myQueueProps is defined as an MQQUEUEPROPS structure to be passed to MQGetQueueProperties: Assign myQueueProps.aPropID[j]=PROPID_Q_LABEL and myQueueProps.aPropVar[j].vt=VT_NULL. When the call returns, myQueueProps.aPropVar[j]. pwszVal points to the buffer that was allocated by MSMQ that contains the queue label.

For Queue and Queue Manager properties whose field type is VT_LPWSTR, VARTYPE must be set to VT_NULL.

In all cases where MSMQ allocates a buffer for the MSMQ application, it is the application's responsibility to free the memory with the MQFreeMemory function.