CreateMsgQueue (Windows CE 5.0)
This function creates or opens a user-defined message queue.
HANDLE CreateMsgQueue(LPCWSTRlpszName,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 the MAX_PATH characters including the NULL character. Each object type, such as memory maps, semaphores, events, message queues, mutexes, and watchdog timers, has its own separate namespace. Empty strings, "", are handled as named objects. On Windows desktop-based platforms, synchronization objects all share the same namespace. - lpOptions
[in] Pointer to an MSGQUEUEOPTIONS structure that sets the properties of the message queue.
Return Values
If the function succeeds, the return value is a read-only or write-only handle to the specified queue. 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 will be 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.
If the function fails, the return value is NULL. To obtain extended error information, call the GetLastError function.
Remarks
If you set the lpszName parameter to NULL, the CreateMsgQueue function creates a new unnamed queue. In the OpenMsgQueue function, you can use the handle returned by the CreateMsgQueue function to obtain additional handles.
If you call the CreateMsgQueue function with a name that already exists, the function uses only the dwSize and bReadAccess values in the structure pointed to by the lpOptions parameter.
You can only create a queue for either read or write access by specifying bReadAccess in the MSGQUEUEOPTIONS structure. You can call CreateMsgQueue twice to obtain a read-only and write-only handle. Use the CloseMsgQueue function to close an object handle returned by CreateMsgQueue.
You can use the handles returned from CreateMsqQueue 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
OS Versions: Windows CE .NET 4.0 and later.
Header: Msgqueue.h.
Link Library: Coredll.lib.
See Also
Message Queue Point-to-Point | CloseMsgQueue | GetMsgQueueInfo | MSGQUEUEINFO | MSGQUEUEOPTIONS | OpenMsgQueue | ReadMsgQueue | WaitForMultipleObjects | WaitForSingleObject | WriteMsgQueue
Send Feedback on this topic to the authors