1. Programming A Distributed Message Queue Application Raphi Renous Software Development Engineer Desktop And Business Systems Division Microsoft Corporation ™

2. Agenda “Falcon” (MSMQ) features Distributed whiteboard demo C/C++ API
ActiveX™ Components
Summary
Questions?

3. “Falcon” (MSMQ) Features
Sessionless with asynchronous send and receive
Protocol and platform-independent API
Scalable to large number of nodes
Robust: reliable, guaranteed, transactional
Integrated security
System-wide priority policy
Advanced logging and tracking
Multireader, multisender, multithreaded
Support for legacy systems
SDK: C/C++ API, ActiveX Components

4. Demo Distributed whiteboard

5. C/C++ API Function sets
Queue manipulation
Queue location
Message manipulation
Utilities
Message and queue objects represented using properties
Use MQ.H, MQRT.LIB

6. Properties Properties associated with queues and messages
Each property consists of ID, type, value
Property set
Count
Array of IDs
Array of variants (tagged union) containing type and value
Array of status codes (optional)
ID names: PROPID_Q_* or PROPID_M_*

7. Usage Overview Queue creation Queue opening Form queue property set
Call MQCreateQueue()with property set
Queue opening
Obtain queue format name
By creating the queue
From the queue location function
Set by the application
Call MQOpenQueue()with format name

8. Usage Overview Message reception Message sending
Open queue for receive access
Determine message property set to be received
Call MQReceiveMessage() with open queue handle and property set
If asynchronous, write code to handle message arrival
Message sending
Open queue for send access
Form message property set
Call MQSendMessage() with open queue handle and property set

9. Queue Manipulation
HRESULT MQCreateQueue(IN PSECURITY_DESCRIPTOR pSecurityDesc,
IN OUT MQQUEUEPROPS *pQueueProps,
OUT LPWSTR lpwcsFormatName,
IN OUT LPDWORD lpdwFormatNameLength)
HRESULT MQDeleteQueue(IN LPWSTR lpwcsFormatName)
Default security: get properties/permissions and send
Queue properties
PATHNAME, LABEL, SERVICETYPE, INSTANCE, TRANSACTIONAL, BASEPRIORITY, AUTHENTICATE, JOURNAL, PRIV_LEVEL, QUOTA
PATHNAME property specifies public/private queue
Public
Stored in MSMQ Information Service database
“MachineName\QueueName”
Private
Stored on disk of local machine
“MachineName\Private$\QueueName”

10. Queue Manipulation Format name Specifies how to get to a queue
“Public=QueueInstance”
“Private=MachineGUID\QueueInstance”
“Direct=Protocol:MachineAddress\ QueueName” “Direct=OS:MachineAddress\QueueName”
Not a property
Returned by MQCreateQueue()
Obtained from the properties returned by the queue location functions
Formed by the application

11. Queue Manipulation Subject to queue security
HRESULT MQOpenQueue(IN LPWSTR lpwcsFormatName,
IN DWORD dwAccess,
IN DWORD dwShareMode,
OUT LPQUEUEHANDLE phQueue)
HRESULT MQCloseQueue(IN QUEUEHANDLE hQueue)
Subject to queue security
One type of access per queue handle
MQ_SEND_ACCESS, MQ_RECEIVE_ACCESS, MQ_PEEK_ACCESS
Share mode
0 - available to everyone (must be used for peek and send)
MQ_DENY_RECEIVE_SHARE - only this process can receive

12. Queue Manipulation QUEUEPROPID aPropId[1]; MQPROPVARIANT aPropVar[1];
DWORD cProps = 0;
aPropId[cProps] = PROPID_Q_PATHNAME;
aPropVar[cProps].vt = VT_LPWSTR;
aPropVar[cProps].pwszVal = L“machine\\queue”;
cProps++;
MQQUEUEPROPS propsQueue;
propsQueue.cProps = cProps;
propsQueue.aPropId = aPropId;
propsQueue.aPropVar = aPropVar;
propsQueue.aStatus = NULL;
WCHAR szFormat[MAX_FORMAT_NAME_LEN];
DWORD dwSize = MAX_FORMAT_NAME_LEN;
HRESULT hr = MQCreateQueue(NULL, &propsQueue, szFormat, &dwSize);
QUEUEHANDLE hQueue;
if (!FAILED(hr))
hr = MQOpenQueue(szFormat, MQ_RECEIVE_ACCESS, 0, &hQueue);

13. Queue Location Powerful - do not need to know exact location of queue
HRESULT MQLocateBegin(IN LPCWSTR lpwcsContext,
IN MQRESTRICTION *pRestriction,
IN MQCOLUMNSET *pColumns,
IN MQSORTSET *pSort,
OUT PHANDLE phEnum)
Powerful - do not need to know exact location of queue
Context - starting point in name space (currently NULL)
Restriction set
Property information (ID, type, value)
Comparison operation for each property
Column set - queue properties to be returned by query
Sort set - sort order for results (optional)
Property IDs from column set
Order for each property ID
Returns enumeration handle (does not retrieve results)

14. Queue Location
HRESULT MQLocateNext(IN HANDLE hEnum,
IN OUT DWORD *pcProps,
OUT PROPVARIANT aPropVar[])
HRESULT MQLocateEnd(IN HANDLE hEnum)
Call MQLocateNext() until (*pcProps) on output < (*pcProps) on input
Returns as many “complete” results as possible
Must free memory allocated by “Falcon” (if any) using MQFreeMemory()

15. Queue Location MQPROPERTYRESTRICTION aPropRestriction[1];
DWORD cProps = 0;
aPropRestriction[cProps].rel = PREQ;
aPropRestriction[cProps].prop = PROPID_Q_LABEL;
aPropRestriction[cProps].prval.vt = VT_LPWSTR;
aPropRestriction[cProps].prval.pwszVal = L“label”;
cProps++;
MQRESTRICTION Restriction;
Restriction.cRes = cProps;
Restriction.paPropRes = aPropRestriction;
QUEUEPROPID aPropId[1];
cProps = 0;
aPropId[cProps] = PROPID_Q_INSTANCE;
MQCOLUMNSET Column;
Column.cCol = cProps;
Column.aCol = aPropId;

16. Queue Location DWORD hEnum;
HRESULT hr = MQLocateBegin(NULL, &Restriction, &Column,
NULL, &hEnum);
if (!FAILED(hr)) {
MQPROPVARIANT aPropVar[1];
DWORD cQueue = 1;
hr = MQLocateNext(hEnum, &cQueue, &Column, aPropVar);
if (!FAILED(hr) && cQueue > 0)
WCHAR szFormat[MAX_FORMAT_NAME_LEN];
DWORD dwSize = MAX_FORMAT_NAME_LEN;
hr = MQGuidToFormatName(aPropVar[0].puuid,
szFormat, &dwSize);
... /* Open queue */
MQFreeMemory(apropVar[0].puuid); }
MQLocateEnd(hEnum);

17. Message Manipulation Message properties Always asynchronous
HRESULT MQSendMessage(IN QUEUEHANDLE hDestinationQueue,
IN MQMSGPROPS * pMessageProps,
IN ITransaction * pTransaction)
Message properties
BODY, LABEL, DELIVERY, PRIORITY, TIME_TO_BE_RECEIVED, TIME_TO_REACH_QUEUE, JOURNAL, ACKNOWLEDGE, CORRELATIONID, APPSPECIFIC, ADMIN_QUEUE, RESPONSE_QUEUE, PRIVACYLEVEL, SECURITY_CONTEXT
Always asynchronous
Use TIME_TO_BE_RECEIVED or TIME_TO_REACH_QUEUE property to specify time limit for message to reach destination
Transaction interface
Get from MS® DTC

18. Message Manipulation Action Additional message properties
HRESULT MQReceiveMessage(IN QUEUEHANDLE hSourceQueue,
IN DWORD dwTimeOut,
IN DWORD dwAction,
IN OUT MQMSGPROPS *pMessageProps,
IN OUT LPOVERLAPPED lpOverlapped,
IN PMQRECEIVECALLBACK fnReceiveCallback,
IN HANDLE hCursor,
IN ITransaction * pTransaction)
Action
MQ_ACTION_RECEIVE, MQ_ACTION_PEEK_CURRENT, MQ_ACTION_PEEK_NEXT
Additional message properties
CLASS, MSGID, SENDERID, SRC_MACHINE, SENDER_CERTIFICATE
Allows asynchronous receive
Callback function, Win32® event, Windows NT® completion port
Cursor used to traverse messages in queue
Transaction interface
Get from MS DTC

19. Message Manipulation MSGPROPID aPropId[1]; MQPROPVARIANT aPropVar[1];
DWORD cProps = 0;
WCHAR szBody[MAX_MSG_BODY_LEN];
aPropId[cProps] = PROPID_M_BODY;
aPropVar[cProps].vt = VT_UI1 | VT_VECTOR;
aPropVar[cProps].cab.cElems = sizeof(szBody);
aPropVar[cProps].cab.pElems = (UCHAR *)szBody;
cProps++;
MQMSGPROPS propsMsg;
propsMsg.cProps = cProps;
propsMsg.aPropId = aPropId;
propsMsg.aPropVar = aPropVar;
propsMsg.aStatus = NULL;
HRESULT hr = MQReceiveMessage(hQueue, INFINITE, MQ_ACTION_RECEIVE, &propsMsg, NULL, NULL, NULL, NULL);

20. Other Functions Queue manipulation Message manipulation Utilities
MQGetQueueProperties(), MQSetQueueProperties()
MQGetQueueSecurity(), MQSetQueueSecurity()
Message manipulation
MQCreateCursor(), MQCloseCursor()
Utilities
MQFreeMemory()
MQGetMachineProperties()
MQGuidToFormatName(), MQHandleToFormatName(), MQPathNameToFormatName()

21. ActiveX Components
Provide simple end-user programming model without compromising performance
Support early (vtable) and late (IDispatch) binding
Direct support for most “Falcon” functionality within the object model
No UI required
Usable by any ActiveX Server controller, for example,
Visual Basic® 3.0, Visual Basic 4.0, Visual Basic 5.0
“Denali”
Microsoft® Access
Office 97
Delphi, PowerBuilder

22. Component Model MSMQQueueInfo: queue object
MSMQQueue: instance of open queue
MSMQMessage: message object
MSMQQuery: supports queue location
MSMQQueueInfos: collection of queues
MSMQEvent: asynchronous message arrival notification
Deliverable: mqoa.dll
Contains both implementation and type library

23. Usage Overview Queue creation Queue opening
Set properties in MSMQQueueInfo
Call MSMQQueueInfo.Create
Queue opening
Obtain MSMQQueueInfo
By creating the queue
From MSMQQueueInfos returned by MSMQQuery
Set q = queueinfo.Open

24. Usage Overview Message reception Message sending
mqQueue = queue opened with receive access
If asynchronous
Create MSMQEvent object: set qevent = new MSMQEvent
Call mqQueue.EnableNotification(qevent)
Write qevent_Arrived event handler
Set mqMessage = mqQueue.Receive
Message sending
mqQueue = queue opened with send access
Set properties in mqMessage instance
Call mqMessage.Send(mqQueue)

25. MSMQQueueInfo Describes a queue object Methods Properties
Create, Delete
Open(access, sharemode) as MSMQQueue
access: MQMSG_RECEIVE_ACCESS, MQMSG_SEND_ACCESS, MQMSG_PEEK_ACCESS
sharemode: MQ_DENY_NONE, MQ_DENY_RECEIVE_SHARE
Properties
strLabel, strPathname, guidServiceType, guidQueue, strFormatName
Example ‘ Create queue for my instance Dim qrec As New MSMQQueueInfo qinfo.strPathName = "machine\queue" qinfo.strLabel = "My Draw Queue" qinfo.Create

26. MSMQQueue Describes an open queue instance
A queue can be concurrently open multiple times
One-to-many mapping from MSMQQueueInfo to MSMQQueue
Analogy: MSMQQueueInfo is to MSMQQueue as File is to FileHandle
Provides asynchronous message handling
Manages collection of messages

27. MSMQQueue Methods IsOpen() as Boolean Close Receive() as MSMQMessage
Synchronous message reception
Peek() as MSMQMessage
Synchronous message peeking
EnableNotification(qevent as MSMQEvent)
Turns on asynchronous message notification
Message arrival to queue will now fire qevent_ Arrived event
DisableNotification
Reset
Resets message collection to start
ReceiveNext() / PeekNext() as MSMQMessage
Cursor based synchronous reception/peek

28. MSMQQueue
Properties
lReceiveTimeout, lAccess, lShareMode, queueinfo, lHandle
Error event fired if timeout expires while synchronously waiting to receive message
Example ‘ Create and open a queue for synchronous reception Dim qinfo As New MSMQQueueInfo Dim myQ As MSMQQueue qinfo.strPathName = "machine\queue" qinfo.Create Set myQ = qinfo.Open(MQMSG_RECEIVE_ACCESS, MQ_DENY_NONE)

29. MSMQEvent
Allows user to write single generic event handler to manage message arrival notification of multiple queues
Events
Arrived(byval pdispQueue as Object)
Fired when a new message arrives at queue
ArrivedError(byval pdispQueue as Object, byval error as Long)
Fired to indicate message error in reception

30. MSMQQuery Provides filtered queue location
Returns collection of queue objects
Method
LookupQueue(<selection criteria>) as MSMQQueueInfos
Example ‘ Locate the friend queue Dim queryFriend As New MqQuery Dim qinfosResult As MSMQQueueInfos Set qinfosResult = queryFriend.LookupQueue( strLabel := FriendName, strGuidServiceType := DrawType)

31. MSMQQueueInfos
Manages collection of MSMQQueueInfo objects produced by MSMQQuery
Methods
Reset
Next() as MSMQQueueInfo
Example ‘ Display the queue label for all the queues Dim queryAll As New MSMQQuery Dim qinfos As MSMQQueueInfos Dim qinfoCurrent As MSMQQueueInfo Set qinfos = queryAll.LookupQueue qinfos.Reset Set qinfoCurrent = qinfos.Next While Not qinfoCurrent Is Nothing MsgBox qinfoCurrent.strLabel Set qinfoCurrent = qinfos.Next Wend

32. MSMQMessage Describes a message Method Properties
Send(q as MSMQQueue)
Properties
body, strLabel, delivery, lPriority, lTimeToBeReceived, lTimeToReachQueue, class, id, idCorrelation, lJournal, acknowledge, queueinfoResponse, queueinfoAdmin, queueinfoDest, lAppSpecific
Example ‘ Send the keystroke to the friend Dim OutMsg as New MSMQMessage OutMsg.lPriority = 4 OutMsg.strBody = Chr(KeyAscii) OutMsg.strLabel = "Key: " + OutMsg.strBody OutMsg.Send FriendQ

33. MSMQMessage.body
The body property allows you to send/receive typed messages
Messages can be:
Strings
Arrays of bytes
Persistent ActiveX objects
Support IDispatch and IPersistStream or IPersistStorage
E.g., Office documents, bitmaps

34. Example
‘ send/receive an XL sheet Dim mSend as New MSMQMessage Dim mReceive as MSMQMessage Dim qSend as MSMQQueue Dim qReceive as MSMQQueue
mSend.body = GetObject(“sheet.xls”) mSend.Send qSend
set mReceive = qReceive.Receive
if TypeOf mReceive.body Is Excel.Workbook Then ‘ do XL stuff to message body set xl = mReceive.body end if

35. Limitations
Only Visual Basic 5.0 supports user-defined event handlers to ActiveX Servers
Use WithEvents keyword in declaration
Visual Basic 4.0 can use every other feature
Visual Basic 5.0 example: ‘ Open an existing queue for asynchronous reception Dim WithEvents qevent As MSMQEvent Sub OpenExistingQueue() Dim qinfo As New MSMQQueueInfo qinfo.strPathName = "machine\queue" Set qPeek = qrec.Open(MQMSG_PEEK_ACCESS, 0) Set qevent = New MSMQEvent qPeek.EnableNotification qevent End Sub Private Sub qevent_Arrived(byval q as Object) Dim m As MSMQMessage Set m = q.PeekNext MsgBox "Arrived: " + m.strBody q.EnableNotification qevent End Sub

36. Summary Your mission Today: try Beta2
Run the samples (c_draw and oa_draw)
Write applications using the C/C++ API and ActiveX Components
Soon: deploy “Falcon”-based message queuing applications

37. Summary Your benefit Easy and flexible distributed programming
Asynchronous, sessionless messaging
Not concerned with underlying network and protocols
Not concerned with computer and network reliability
Integrated with state-of-the-art technologies and interfaces
ActiveX Components usable from Visual Basic Scripting Edition (e.g., “Denali”)

38. Questions? For more information
See slides from “Microsoft Message Queue Server Overview (ENT208)” talk
Check out our Web site:
Contact

39. ™