Platform SDK: CDO 1.2.1

Working with Conversations

Two Message object properties let you show relationships among messages by defining them as part of a conversation. A conversation is a series of messages, consisting of an initial message and all messages sent in reply to the initial message. When the initial message or a reply elicits additional messages, the resulting messages are called a conversation thread. A thread represents a subset of messages in the conversation.

The Message object properties ConversationIndex and ConversationTopic give you an easy way to organize and display messages. Rather than simply grouping messages by subject, time received, or sender, you can show conversational relationships among messages. The ConversationTopic property is a string that describes the overall subject of the conversation. All messages within the same conversation use the same value for the ConversationTopic property. The ConversationIndex property is a hexadecimal string that you can use to represent the relationships between the messages in the thread. Each message in the conversation should have a different ConversationIndex property.

When you start an initial message, set the ConversationTopic property to a value appropriate to all messages within the conversation, not only to the first message. For many applications, the message’s Subject property is appropriate.

You can use your own convention to decide how to use the ConversationIndex property. However, it is recommended that you adopt the same convention used by the Microsoft® Exchange Client message viewer, so that you can use that viewer’s user interface to show the relationships between messages in a conversation. This convention uses concatenated time stamp values. The first time stamp in the ConversationIndex string represents the original message. Whenever a message replies to a conversation message, it appends a time stamp value to the end of the string. The new string value is used as the ConversationIndex value of the new message. Using this convention, you can easily see relationships among messages when you sort the messages by ConversationIndex values.

The following code fragment provides a utility function, Util_GetEightByteTimeStamp, which can be used to build Microsoft Exchange Server compatible ConversationIndex values. The utility function calls the OLE function CoCreateGuid to obtain the time stamp value from a GUID data structure. The GUID value is composed of a time stamp and a machine identifier; the utility function saves the part that contains the time stamp.

' declarations for the Util_GetEightByteTimeStamp function 
Type GUID 
    Guid1 As Long 
    Guid2 As Long 
    Guid3 As Long 
    Guid4 As Long 
End Type 
Declare Function CoCreateGuid Lib "COMPOBJ.DLL" (pGuid As GUID) As Long 
' Note: Use "OLE32.DLL" for Windows NT, Win95 platforms 
Global Const S_OK = 0 
' end declarations section 
 
' Function: Util_GetEightByteTimeStamp 
' Purpose: Generate a time stamp for use in conversations 
' See documentation topic: Working With Conversations 
Function Util_GetEightByteTimeStamp() As String 
Dim lResult As Long 
Dim lGuid As GUID 
' Exchange conversation is a unique 8-byte value 
' Exchange client viewer sorts by concatenated properties 
On Error GoTo error_olemsg 
 
lResult = CoCreateGuid(lGuid) 
If lResult = S_OK Then 
    Util_GetEightByteTimeStamp = Hex$(lGuid.Guid1) & Hex$(lGuid.Guid2) 
Else 
    Util_GetEightByteTimeStamp = "00000000" ' zeroes 
End If 
Exit Function 
 
error_olemsg: 
MsgBox "Error " & Str(Err) & ": " & Error$(Err) 
Util_GetEightByteTimeStamp = "00000000" 
Exit Function 
 
End Function 
 

When you start a new conversation, set the ConversationIndex property to the value returned by this function, as follows:

' new conversation 
objMessage.ConversationIndex = Util_GetEightByteTimeStamp() 
 

When you are replying to a message in an existing conversation, append the time stamp value to that message’s ConversationIndex value, as follows:

' reply within an existing conversation 
Dim objOriginalMsg As Message ' assume valid 
Dim objNewMessage As Message  ' new message in conversation 
Dim strNewIndex As String 
' ... 
' copy the original topic and append 
'      the current time stamp to the original time stamp 
objNewMessage.ConversationTopic = objOriginalMsg.ConversationTopic 
strNewIndex = objOriginalMsg.ConversationIndex _ 
                             & Util_GetEightByteTimeStamp() 
objNewMessage.ConversationIndex = strNewIndex 
 

For additional sample code dealing with conversations, see Posting Messages to a Public Folder.