Presentation is loading. Please wait.

Presentation is loading. Please wait.

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

Similar presentations

Presentation on theme: "Programming A Distributed Message Queue Application Raphi Renous Software Development Engineer Desktop And Business Systems Division Microsoft Corporation."— Presentation transcript:

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


Download ppt "Programming A Distributed Message Queue Application Raphi Renous Software Development Engineer Desktop And Business Systems Division Microsoft Corporation."

Similar presentations

Ads by Google