WinWaitForShell: Difference between revisions

Revision as of 03:08, 29 December 2016

WinWaitForShell

WinWaitForShell(event): Allows an application to wait for the Workplace Shell to become available.

Syntax

#define
#include <os2.h>

 BOOL EXPENTRY WinWaitForShell (ULONG ulEvent)

Parameters

ulEvent (ULONG) input: ulEvent has the following flags which indicate which event is to be queried. One, and only one, of these flags must be turned on.

Constants defined for event:

WWFS_QUERY - Query if the event has taken place. If this flag is not turned on then this call will block until the event has taken place.
WWFS_DESKTOPCREATED - Desktop has been created.
WWFS_DESKTOPOPENED - A view of the Desktop has been opened.
WWFS_DESKTOPPOPULATED - The desktop has been populated.

Returns

Returns BOOL with the values of:

TRUE - Event has taken place.
FALSE - Event has not taken place.
PMERR_INVALID_PARAMETER (0x1208) - One of the defined WWFS_DESKTOP* flags was not passed in ulEvent.

Define (C/C++)

INCL_WINWORKPLACE

Export name/Ordinal

Exported as ordinal 512 from PMWP.DLL.

Calling conversion

Cdecl32

Example Code

BOOL rc;
...
rc = WinWaitForShell(WWFS_DESKTOPPOPULATED); // Desktop populated
...

Related Functions

WinNotebookButtonFromID

Notes

When calling WinWaitForShell from processes started by a RUN= statement in config.sys, you must specify the WWFS_QUERY flag. Else the call will fail.

A message queue is not required for the thread which calls WinWaitForShell.

The prototype and defines for this function are defined in wpobject.h, which may be inaccessible if not compiling a WPS object class. Copy the defines and the prototype verbatim into your own code or headers for use. It is exported through os2386.lib in the OS/2 Warp 4 Toolkit.

OS Version Introduced

OS/2 Warp 4

Implementation details

This function queries or waits for three event semaphores created by WinStartShell during WPS bootup. These events are:

\\SEM32\\WORKPLAC\\SHELL1WT.SEM
\\SEM32\\WORKPLAC\\SHELL2WT.SEM
\\SEM32\\WORKPLAC\\SHELL3WT.SEM

Each according to the three WWFS-constants. Calling WinWaitForShell before the second instance of PMShell is started is valid as long as the WWFS_QUERY bit is specified.

Once posted, the events are not reset again, so to be able to wait for the shell to come back up after resetting it programmatically, the events must be reset by the calling process. Reset the events right before killing WPS, not before calling WinWaitForShell.

Example Code

This example checks (non-blocking) to see if the Workplalce Shell Desktop to be populated has been populated or not.

#define
#include  <os2.h>

BOOL fOccurred;

fOccurred + WinWaitForShell(WWFS_DESKTOPPOPULATED | WWFS_QUERY);
if (fOccurred)
   {
    /* The Desktop has been populated */
   }
else
   {
    /* The Desktop has not been populated */

@@ Line 1: / Line 1: @@
 == WinWaitForShell ==
-; WinWaitForShell(event) : Allows an application to wait for the Workplace Shell to become available.
+;WinWaitForShell(event) : Allows an application to wait for the Workplace Shell to become available.
 ==Syntax==
 <PRE>
 #define
-#include  <os2.h>
+#include <os2.h>
-    BOOL EXPENTRY WinWaitForShell (ULONG ulEvent)
+ BOOL EXPENTRY WinWaitForShell (ULONG ulEvent)
 </PRE>
 === Parameters ===
-; ulEvent (ULONG) input : ulEvent has the following flags which indicate which event is to be queried. One, and only one, of these flags must be turned on.
+;ulEvent (ULONG) input : ulEvent has the following flags which indicate which event is to be queried. One, and only one, of these flags must be turned on.
 Constants defined for event:
-* [[OS2 API:Constant:WWFS#WWFS_QUERY|WWFS_QUERY]] - Query if the event has taken place. If this flag is not turned on then this call will block until the event has taken place.
+* [[WWFS|WWFS_QUERY]] - Query if the event has taken place. If this flag is not turned on then this call will block until the event has taken place.
-* [[OS2 API:Constant:WWFS#WWFS_DESKTOPCREATED|WWFS_DESKTOPCREATED]] - Desktop has been created.
+* [[WWFS|WWFS_DESKTOPCREATED]] - Desktop has been created.
-* [[OS2 API:Constant:WWFS#WWFS_DESKTOPOPENED|WWFS_DESKTOPOPENED]] - A view of the Desktop has been opened.
+* [[WWFS|WWFS_DESKTOPOPENED]] - A view of the Desktop has been opened.
-* [[OS2 API:Constant:WWFS#WWFS_DESKTOPPOPULATED|WWFS_DESKTOPPOPULATED]] - The desktop has been populated.
+* [[WWFS|WWFS_DESKTOPPOPULATED]] - The desktop has been populated.
 === Returns ===
-Returns [[OS2_API:DataType:BOOL|BOOL]] with the values of:
+Returns [[BOOL]] with the values of:
-* [[OS2_API:Constant:TRUE|TRUE]] - Event has taken place.
+*[[TRUE]] - Event has taken place.
-* [[OS2_API:Constant:FALSE|FALSE]] - Event has not taken place.
+*[[FALSE]] - Event has not taken place.
-*  PMERR_INVALID_PARAMETER (0x1208) - One of the defined WWFS_DESKTOP* flags was not passed in ulEvent.
+*PMERR_INVALID_PARAMETER (0x1208) - One of the defined WWFS_DESKTOP* flags was not passed in ulEvent.
-=== Module ===
 === Define (C/C++) ===
@@ Line 43: / Line 42: @@
 === Related Functions ===
-[[OS2 API:WinNotebookButtonFromID|WinNotebookButtonFromID]]
+*[[WinNotebookButtonFromID]]
 === Notes ===
-When calling [[OS2 API:WinWaitForShell|WinWaitForShell]] from processes started by a RUN= statement in config.sys, you must specify the WWFS_QUERY flag. Else the call will fail.
+When calling '''WinWaitForShell''' from processes started by a RUN= statement in config.sys, you must specify the WWFS_QUERY flag. Else the call will fail.
-A message queue is not required for the thread which calls [[OS2_API:WinWaitForShell|WinWaitForShell]].
+A message queue is not required for the thread which calls '''WinWaitForShell'''.
 The prototype and defines for this function are defined in wpobject.h, which may be inaccessible if not compiling a WPS object class. Copy the defines and the prototype verbatim into your own code or headers for use. It is exported through os2386.lib in the OS/2 Warp 4 Toolkit.
@@ Line 56: / Line 55: @@
 === Implementation details ===
-This function queries or waits for three event semaphores created by [[OS2 API:WinStartShell|WinStartShell]] during WPS bootup. These events are:
+This function queries or waits for three event semaphores created by [[WinStartShell]] during WPS bootup. These events are:
   \\SEM32\\WORKPLAC\\SHELL1WT.SEM
   \\SEM32\\WORKPLAC\\SHELL2WT.SEM
   \\SEM32\\WORKPLAC\\SHELL3WT.SEM
-Each according to the three [[OS2 API:Constant:WWFS|WWFS-constants]]. Calling [[OS2_API:WinWaitForShell|WinWaitForShell]] before the second instance of PMShell is started is valid as long as the [[OS2 API:Constant:WWFS#WWFS_QUERY|WWFS_QUERY]] bit is specified.
+Each according to the three [[WWFS|WWFS-constants]]. Calling '''WinWaitForShell''' before the second instance of PMShell is started is valid as long as the [[WWFS|WWFS_QUERY]] bit is specified.
-Once posted, the events are not reset again, so to be able to wait for the shell to come back up after resetting it programmatically, the events must be reset by the calling process. Reset the events right before killing WPS, not before calling [[OS2 API:WinWaitForShell|WinWaitForShell]].
+Once posted, the events are not reset again, so to be able to wait for the shell to come back up after resetting it programmatically, the events must be reset by the calling process. Reset the events right before killing WPS, not before calling '''WinWaitForShell'''.
 ==Example Code==
 This example checks (non-blocking) to see if the Workplalce Shell Desktop to be populated has been populated or not.
 <PRE>
-#define#include  <os2.h>
+#define
+#include  <os2.h>
 BOOL fOccurred;
@@ Line 83: / Line 80: @@
     {
      /* The Desktop has not been populated */
 </PRE>
-[[Category:The OS/2 API Project]]
+[[Category:Win]]