CreateMsgQueue

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function creates or opens a user-defined message queue.

Syntax

HANDLE CreateMsgQueue(
  LPCWSTR lpszName,
  LPMSGQUEUEOPTIONS lpOptions
);

Parameters

• lpszName
  [in] Name of the message queue. You can also set this parameter to NULL or you must set it no larger than: MAXPATH characters, including the NULL character.

• lpOptions
  [in] Pointer to an MSGQUEUEOPTIONS structure that sets the properties of the message queue.

Return Value

A read-only or write-only handle to the specified queue indicates success.

If a read-only handle is returned, the queue signals when data is put into the queue. The signal is reset in the ReadMsgQueue function. If a write-only handle is returned, the queue signals when the queue is no longer full. If the specified queue exists before the function call, a new handle is created that points to the same queue. The queue already exists if a call to the GetLastError function returns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the message queue does not exist before the call, GetLastError returns ERROR_SUCCESS.

NULL indicates failure. To obtain extended error information, call the GetLastError function.

Remarks

In the OpenMsgQueue function, you can use the handle returned by this function to obtain additional handles.

If you call this function with a name that already exists, the function uses only the dwSize, bReadAccess, and cbMaxMessage values in the structure pointed to by lpOptions.

You can create a queue for either read or write access by specifying bReadAccess in the MSGQUEUEOPTIONS structure. You can call this function twice to obtain a read-only and write-only handle. Use the CloseMsgQueue function to close an object handle returned by this function.

You can use the handles returned by this function in calls to the WaitForSingleObject or WaitForMultipleObjects functions. Returned handles can indicate a time-out or that the status of the queue has changed.

Writable queue handles are signaled whenever the queue is not full, and readable queue handles are signaled if the queue is not empty. For example, a writer can WaitForSingleObject(hQ, INFINITE) to know that a queue is not full and that it's safe to write and a reader can WaitForSingleObject(hQ, INFINITE) no matter how many messages are in the queue.

Requirements

See Also

Reference

Message Queue Point-to-Point Functions
CloseMsgQueue
GetMsgQueueInfo
MSGQUEUEINFO
MSGQUEUEOPTIONS
OpenMsgQueue
ReadMsgQueue
WriteMsgQueue

Other Resources

Message Queue Point-to-Point