Jump to content

WinWaitForShell: Difference between revisions

From EDM2
← Older edit
Prokushev (talk | contribs)
400 edits
No edit summary
No edit summary
 
(25 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== WinWaitForShell ==
; WinWaitForShell(ulEvent) :
Allows an application to wait for the Workplace Shell to become available.
Allows an application to wait for the Workplace Shell to become available.


=== Parameters ===
WinWaitForShell determines if various events in the Workplace Shell(R) have taken place.
; ulEvent - [[OS2_API:DataType:ULONG|ULONG]] - input :
The event to wait for.


=== Constants ===
==Syntax==
The following constants are defined for the parameter ulEvent:
WinWaitForShell (ulEvent)


#define WWFS_QUERY            0x80000000
==Parameters==
#define WWFS_DESKTOPCREATED  1
;''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.
#define WWFS_DESKTOPOPENED    2
#define WWFS_DESKTOPPOPULATED 3


=== Returns ===
[[WWFS|Constants]] defined for event:
This function returns a [[OS2_API:DataType:BOOL|BOOL]] with the values of:
*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:DataType:TRUE|TRUE]]
*WWFS_DESKTOPCREATED - Desktop has been created.
* [[OS2_API:DataType:FALSE|FALSE]]
*WWFS_DESKTOPOPENED - A view of the Desktop has been opened.
*WWFS_DESKTOPPOPULATED - The desktop has been populated.


=== Module ===
==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.


== Export name/Ordinal ==
Exported as ordinal 512 from PMWP.DLL.


=== Define (C/C++) ===
== Calling Convention ==
[[Cdecl32]]
 
== 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.
 
==Remarks==
This function can be used to either determine if a Workpalce Shell event has taken place or wait until that event has taken place. Set ulEvent to one of the WWFS_DESKTOP* #defines above.
 
To block until the event has occurred, do not turn on the WWFS_QUERY flag.


=== Export name/Ordinal ===
Simply to query if the event has occurred and not to wait for it to occur, turn on the WWFS_QUERY flag.


=== Calling conversion ===
== OS Version Introduced ==
[[Cdecl32]]
OS/2 Warp 4


=== Example Code ===
== Implementation details ==
#define INCL_WINWORKPLACE
This function queries or waits for three event semaphores created by ''WinStartShell'' during WPS bootup. These events are:
  #define INCL_WINDIALOGS
  \\SEM32\\WORKPLAC\\SHELL1WT.SEM
  #define INCL_WIN
  \\SEM32\\WORKPLAC\\SHELL2WT.SEM
  #include <os2.h>
  \\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.
// Define function not found in headers
BOOL APIENTRY WinWaitForShell( ULONG ulEvent );
#define WWFS_QUERY           0x80000000
#define WWFS_DESKTOPCREATED  1
#define WWFS_DESKTOPOPENED    2
#define WWFS_DESKTOPPOPULATED 3
int main(int argc, char *argv[])
{
    HAB  hab;
    HMQ  hmq;
    BOOL fShellPopulated;
    fShellPopulated = WinWaitForShell(WWFS_DESKTOPPOPULATED); // Desktop populated
    if (fShellPopulated) {
      DosBeep(440, 1000);
      hab = WinInitialize(0);
      hmq = WinCreateMsgQueue(hab, 0);
      WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, "Desktop was populated", "Message", 0x100, MB_OK|MB_ICONASTERISK);
      WinDestroyMsgQueue(hmq);
      WinTerminate(hab);
    } else {
      DosBeep(220, 1000);
    }
    return 0;
}


=== Related Functions ===
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''.


=== Notes ===
==Example Code==
WinWaitForShell can not be called from detached processes. So a program started by
Definition:
a RUN= statement in config sys, can not rely on this method to wait for the shell
<pre>
to be up.
#define
#include  <os2.h>


A message queue is not required for the thread which calls WinWaitForShell.
    BOOL EXPENTRY WinWaitForShell(ULONG ulEvent)
</pre>


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.
This example checks (non-blocking) to see if the Workplace Shell Desktop to be populated has been populated or not.
<pre>
#define  INCL_WINWORKPLACE
#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 */
</pre>
==Related Functions==
*[[WinNotebookButtonFromID]]


=== OS Version Introduced ===
[[Category:Win]]
OS/2 Warp 4

Latest revision as of 03:57, 16 May 2025

Allows an application to wait for the Workplace Shell to become available.

WinWaitForShell determines if various events in the Workplace Shell(R) have taken place.

Syntax

WinWaitForShell (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.

Export name/Ordinal

Exported as ordinal 512 from PMWP.DLL.

Calling Convention

Cdecl32

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.

Remarks

This function can be used to either determine if a Workpalce Shell event has taken place or wait until that event has taken place. Set ulEvent to one of the WWFS_DESKTOP* #defines above.

To block until the event has occurred, do not turn on the WWFS_QUERY flag.

Simply to query if the event has occurred and not to wait for it to occur, turn on the WWFS_QUERY flag.

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

Definition: 

#define
#include  <os2.h>

    BOOL EXPENTRY WinWaitForShell(ULONG ulEvent)

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

 #define  INCL_WINWORKPLACE
 #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 */

Related Functions

Retrieved from "https://www.edm2.com/index.php?title=WinWaitForShell&oldid=87099"