SHCameraCapture

Article
08/28/2006

The SHCameraCapture function launches the Camera Capture dialog box, which allows the user to capture still images and video clips.

Syntax

HRESULT SHCameraCapture (
  PSHCAMERACAPTURE pshcc
);

Parameters

pshcc
[in/out] Reference to an SHCAMERACAPTURE structure, which contains information that initializes the SHCameraCapture function, and also contains a reference to the fully-qualified path-name of the captured picture file or video file.

Return Values

S_OK
The method completed successfully.
S_FALSE
The user canceled the Camera Capture dialog box.
E_OUTOFMEMORY
There is not enough memory to save the image or video.
E_INVALIDARG
An invalid argument was specified.

Remarks

When the SHCameraCapture function returns successfully, the buffer pointed to by **SHCAMERACAPTURE::**szFile contains the fully-qualified path-name of the picture file or video file.

Application writers should be aware that SHCameraCapture function can cause the calling application to stop responding in cases where the calling application is minimized and then reactivated while the call to SHCameraCapture function is still blocking.

A possible sequence of events can be as follows:

User launches an application
Application calls SHCameraCapture
User minimizes the application while the Camera view is active
User reactivates the application

Rather than going back to Camera view, the user will see the calling application, and it will stop responding.

You should take both of the following steps to avoid these types of issues when calling this API:

Don't use the WS_POPUP window style in the window that calls SHCameraCapture.
When your application is being reactivated, determine whether it is still blocking on a call to SHCameraCapture and if it is, bring the Camera window to the foreground. You can find the Camera window by calling FindWindow(TEXT("Camera View"), NULL).

The following code example shows how to overcome this problem.

// The class name of the Camera window.
#define CAMERAWND_CLASSNAME TEXT("Camera View")

// The message to activate the Camera window.
#define WM_ACTIVATE_CAMERAVIEW WM_USER + 1

// The flag to determine if the Camera window is running.
BOOL g_bCameraRunning = FALSE;

// The sample function of calling SHCameraCapture()
HRESULT CameraCaptureExample(HWND hwndOwner, LPTSTR pszFilename)
{
   HRESULT hResult;
   SHCAMERACAPTURE shcc;

   // Set the SHCAMERACAPTURE structure.
   // Set g_bCameraRunning flag as TRUE before we call SHCameraCapture() function.
   g_bCameraRunning = TRUE;

   // Display the Camera Capture dialog.
   hResult = SHCameraCapture(&shcc);

   // Set g_bCameraRunning flag as FALSE after we called SHCameraCapture() function.
   g_bCameraRunning = FALSE;

   return hResult;
}

// The window procedure of app's window
LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
{
   switch (uMsg)
   {
      case WM_ACTIVATE:
         if (WA_ACTIVE == LOWORD(wParam) && g_bCameraRunning)
         {
            PostMessage(hwnd, WM_ACTIVATE_CAMERAVIEW, 0, 0);
         }
         break;
      case WM_ACTIVATE_CAMERAVIEW:
         if (g_bCameraRunning)
         {
            // Reactivate the camera window if camera window is running
            HWND hwndCamera = FindWindow(CAMERAWND_CLASSNAME, NULL);
            if (NULL != hwndCamera)
            {
               // Bring the last active window owned by camera window to the foreground
               SetForegroundWindow(GetLastActiveWindow(hwndCamera));
            }
         }
         break;

// Determine if hwnd is owned by hwndOwner.
BOOL IsOwned(HWND hwndOwner, HWND hwnd)
{
   BOOL bOwned = FALSE;
   while (NULL != (hwnd = GetWindow(hwnd, GW_OWNER)))
   {
      if (hwnd == hwndOwner)
      {
         bOwned = TRUE;
         break;
      }
   }
return bOwned;
}

// Get the topmost, visible, enabled window who is owned by the window
// which specified by the application-defined value given in EnumWindows.
BOOL CALLBACK EnumLastActiveWindowProc(HWND hwnd, LPARAM lParam)
{
   BOOL bContinue = TRUE;
   HWND hOwner = *((HWND *)lParam);

   // Ignore windows which are invisible, disabled or cannot be activated.
   if (!IsWindowVisible(hwnd) || !IsWindowEnabled(hwnd) || (WS_EX_NOACTIVATE & GetWindowExStyle(hwnd)))
   {
   // Continue enumeration.
   goto Exit;
   }

   // If this is the owner window, there are no owned windows because
   // all owned windows are always above its owner in the z-order.
   if (hwnd == hOwner)
   {
   // Not found the owned window. Stop enumeration.
      bContinue = FALSE;
      goto Exit;
   }
   // Is this window owned by hwndOwner?
   if (IsOwned(hOwner, hwnd))
   {
      // Found the last owned window. Stop enumeration.
      bContinue = FALSE;
      *((HWND *)lParam) = hwnd;
      goto Exit;
   }
   Exit:
      return bContinue;
}

// Retrieves the last active window owned by hwndOwner.
HWND GetLastActiveWindow(HWND hwndOwner)
{
   HWND hwndLastActive = hwndOwner;
   EnumWindows(EnumLastActiveWindowProc, (LPARAM)&hwndLastActive);
   return hwndLastActive;
}

Code Example

The following code example demonstrates how to use SHCameraCapture.

Note To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

HRESULT CameraCaptureExample(HWND hwndOwner, LPTSTR pszFilename)
{
    HRESULT         hResult;
    SHCAMERACAPTURE shcc;

    // Set the SHCAMERACAPTURE structure.
    ZeroMemory(&shcc, sizeof(shcc));
    shcc.cbSize             = sizeof(shcc);
    shcc.hwndOwner          = hwndOwner;
    shcc.pszInitialDir      = TEXT("\\My Documents");
    shcc.pszDefaultFileName = TEXT("test.3gp");
    shcc.pszTitle           = TEXT("Camera Demo");
    shcc.VideoTypes         = CAMERACAPTURE_VIDEOTYPE_MESSAGING;
    shcc.nResolutionWidth   = 176;
    shcc.nResolutionHeight  = 144;
    shcc.nVideoTimeLimit    = 15;
    shcc.Mode               = CAMERACAPTURE_MODE_VIDEOWITHAUDIO;

    // Display the Camera Capture dialog.
    hResult = SHCameraCapture(&shcc);

    // The next statements will execute only after the user takes
    // a picture or video, or closes the Camera Capture dialog.
    if (S_OK == hResult)
    {
        StringCchCopy(pszFilename, MAX_PATH, shcc.szFile);
    }

    return hResult;
}

Requirements

Pocket PC: Windows Mobile 5.0 and later.
Smartphone: Windows Mobile 5.0 and later.
OS Versions: Windows CE 5.01 and later.
Header: Aygshell.h.

Share via