WinRestoreWindowPos

This function obtains the title under which a specified application is started, or is added to the Window List.

Syntax

WinQuerySessionTitle(hab, ulSession, pszTitle, ulTitlelen);

Parameters

hab (HAB) - input

Anchor-block handle.

ulSession (ULONG) - input

Session identity of application whose title is requested.

Use the session identity of the caller Other

Use the specified session identity.

pszTitle (PSZ) - output

Window List title.

This is the title of the application with a process identity, if the application is present in the Window List.

ulTitlelen (ULONG) - input

Maximum length of data returnable, in bytes.

If the pszTitle parameter is longer than this value, the title is truncated. However, the terminating null character is left at the end of the string. The maximum number of title characters copied is (ulTitlelen-1).

Returns

rc (ULONG) - returns

Return code.

Successful completion

Other

Error occurred.

Remarks

This function is useful when an application uses the same name in its window title (and in its entry in the Window List) as the end user invokes to start the application. This provides a visual link for the end user.

If this function is used after a Window List entry is created for the application, the title in the Window List entry is obtained. (See also WinQueryTaskTitle.)

Example Code

This example calls WinQuerySessionTitle to retrieve the application's title, and then sets the title bar of the frame window to that title.

#define INCL_WINMESSAGEMGR
#define INCL_WINWINDOWMGR
#include <OS2.H>

HAB  hab;
HWND hwndFrame, hwndClient;
CHAR szTitle[MAXNAMEL + 1];

WinQuerySessionTitle(hab,
                     0,
                     szTitle,
                     sizeof(szTitle));

hwndFrame = WinQueryWindow(hwndClient,
                           QW_PARENT); /* get handle of parent, */
                                          /* which is frame window. */
WinSetWindowText(hwndFrame, szTitle);

Definition

#define INCL_WINSWITCHLIST /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HAB      hab;         /*  Anchor-block handle. */
ULONG    ulSession;   /*  Session identity of application whose title is requested. */
PSZ      pszTitle;    /*  Window List title. */
ULONG    ulTitlelen;  /*  Maximum length of data returnable, in bytes. */
ULONG    rc;          /*  Return code. */

rc = WinQuerySessionTitle(hab, ulSession,
       pszTitle, ulTitlelen);

Related Functions

• WinAddSwitchEntry
• WinChangeSwitchEntry
• WinCreateSwitchEntry
• WinQuerySessionTitle
• WinQuerySwitchEntry
• WinQuerySwitchHandle
• WinQuerySwitchList
• WinQueryTaskSizePos
• WinQueryTaskTitle
• WinRemoveSwitchEntry
• WinSwitchToProgram