SHCAMERACAPTURE (structure)

  • Article

4/8/2010

The Windows Mobile SHCAMERACAPTURE structure contains information used to initialize the SHCameraCapture function. It also contains a reference to the fully-qualified path-name of the captured picture file or video file.

Syntax

struct {
  DWORD cbSize;
  HWND hwndOwner;
  TCHAR szFile[MAX_PATH];
  LPCTSTR pszInitialDir;
  LPCTSTR pszDefaultFileName;
  LPCTSTR pszTitle;
  CAMERACAPTURE_STILLQUALITY StillQuality;
  CAMERACAPTURE_VIDEOTYPES VideoTypes;
  DWORD nResolutionWidth;
  DWORD nResolutionHeight;
  DWORD nVideoTimeLimit;
  CAMERACAPTURE_MODE Mode;
} SHCAMERACAPTURE, *PSHCAMERACAPTURE;

Members

  • cbSize
    The size of SHCAMERACAPTURE structure, in bytes.
  • hwndOwner
    A handle to the owner window. Can be NULL.
  • szFile
    The fully-qualified path-name of the captured picture file or video file (provided the SHCameraCapture function returns successfully).
  • pszInitialDir
    Specifies the directory for storing the captured picture or video file. If NULL, the image is stored in the directory defined in Pictures & Video > Camera Options > Save files to:. If the directory does not exist, an E_INVALIDARG error is generated.
  • pszDefaultFileName
    Specifies the file name for the captured still image or video clip. Still images on Windows Mobile devices conform to the JPEG standard. As a result, file names for still images must end in *.jpg. There is no restriction for naming video files, other than the file format must be supported by Windows Media Player Mobile. Since different video encoders can use differing naming conventions, it is important that the file name has the correct extension. To be safe, you can simply use NULL when naming Video files. If pszDefaultFileName is NULL, then the file name specified in Pictures & Video > Camera Options > Type filename prefix: is used. If the file already exists, it is overwritten. The combination of InitialDirectory and DefaultFileName must not exceed 256 characters.
  • pszTitle
    The title of the Camera Capture dialog box. If NULL, the default title of "Pictures & Videos" is used.
  • StillQuality
    One of the CAMERACAPTURE_STILLQUALITY enumeration values, which specifies the quality of the captured still image. The default is normal quality (CAMERACAPTURE_STILLQUALITY_NORMAL).

  • VideoTypes
    One of the CAMERACAPTURE_VIDEOTYPES enumeration values, which specifies a video quality profile (i.e., whether the video clip is to be used by an MMS application).

    Note

    If nResolutionWidth and nResolutionHeight both equal 0, and VideoTypes equals CAMERACAPTURE_VIDEOTYPE_ALL, then the user's last selected resolution is used. For VideoTypes values of CAMERACAPTURE_VIDEOTYPE_STANDARD and CAMERACAPTURE_VIDEOTYPE_MESSAGING, either nResolutionWidth or nResolutionHeight must not equal 0.

  • nResolutionWidth
    The image width, in pixels. When nResolutionWidth equals 0 for video clips, then CAMERACAPTURE_VIDEOTYPES enumeration values are considered the only valid values for use in selecting video profiles.
  • nResolutionHeight
    The image height, in pixels. When nResolutionHeight equals 0 for video clips, then CAMERACAPTURE_VIDEOTYPES enumeration values are considered the only valid values for use in selecting video profiles.
  • nVideoTimeLimit
    The maximum length of time in seconds, allowed for a video clip. A time limit of 0 indicates that there is no limitation. The default is 0 (no limit).

Remarks

Multimedia Messaging Service (MMS) applications must be able to capture video that meets criteria specific to multimedia messaging. This includes video format and file size. To accommodate this, it is up to the Original Equipment Manufacturer (OEM) who is making the Windows Mobile device to register Video Profiles for each of the Video Types (All, Standard, and Messaging). To be compliant, you just need to call SHCameraCapture with a Video Type and video resolution that matches one of the Video Profiles.

  • Video Type specifies whether the video should be recorded in a format that is compatible with video messaging (usually encoded in either MPEG4 format or H.263 format), or for use in home videos and e-mail messaging (usually encoded in Windows Media Video (WMV) format).
  • Video Profiles are registry settings that contain a combination of Video Type, video encoder, video resolution, and a profile name.

When you call the SHCameraCapture function, the Video Type and video resolution that you specify are matched to a corresponding Video Profile to determine which Video Profile is used to initialize video capture mode. Your CAMERACAPTURE_VIDEOTYPES value is logically ANDed (&) with the VideoType value in each registered profile (e.g., "VideoType:DWORD = 0x0002" for messaging). Of those that produce a 1, the video resolutions are then compared. If a matching Video Profile is found, then it is used to initialize video capture mode. If one cannot be found, then E_INVALIDARG is returned. In this case, you should just call SHCameraCapture again, this time with a CAMERACAPTURE_VIDEOTYPES value of CAMERACAPTURE_VIDEOTYPE_ALL (0xFFFF), and no specified video resolution; the first supported video resolution will then be used.

The following example demonstrates a typical video profile registration.

HKEY_LOCAL_MACHINE\Software\Microsoft\Pictures\Camera\OEM\VideoProfile\1
ItemString:String = "MMS (174x144)"
VideoType:DWORD = 0x0002 ; For messaging
Width:DWORD = 176
Height:DWORD = 144
...; Setting for the encoder

You can estimate the video file size that meets the time-limit restriction by specifying a particular video resolution.

Each Video Profile is listed as an option for the user in Pictures & Video > Menu > Quality.

Requirements

Header aygshell.h
Library Aygshell.dll
Windows Mobile Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

See Also

Reference

Shell Structures
SHCameraCapture
CAMERACAPTURE_MODE
CAMERACAPTURE_STILLQUALITY
CAMERACAPTURE_VIDEOTYPES

Other Resources

Camera Capture
Camera Capture Graph