Defining a New Data Structure

The fields of the data structure for a media control interface message are always the size of ULONGs. The number of fields in the structure depends on the particular message. The first field must be reserved for a handle to a window function used with the MCI_NOTIFY flag. The next fields in the data structure depend on the type of data returned for the message.

• If no data is returned, no return fields are reserved in the data structure. Any data fields for passing information to the MCD immediately follow the hwndCallback field. For example, the MCI_SAVE_PARMS structure shown in the following figure does not have a return field.

  typedef struct _MCI_SAVE_PARMS {
      HWND    hwndCallback;    /* PM window handle for MCI notify message */
      PSZ     pszFileName;     /* File name to save data to               */
   } MCI_SAVE_PARMS;
  typedef MCI_SAVE_PARMS   *PMCI_SAVE_PARMS;
  

• If integer data is returned, the second field of the data structure is reserved for the return data. Any data fields for passing information to the MCD start in the third field. For example, the MCI_GETDEVCAPS_PARMS structure shown in the following example uses ulReturn as the integer return field.

  typedef struct _MCI_GETDEVCAPS_PARMS {
      HWND    hwndCallback;    /* PM window handle for MCI notify message */
      ULONG   ulReturn;        /* Return field                            */
      ULONG   ulItem;          /* Item field for GETDEVCAPS item to query */
      USHORT  usMessage;       /* Field to hold MCI message to query      */
      USHORT  usReserved0;     /* Reserved field                          */
  } MCI_GETDEVCAPS_PARMS;
  typedef MCI_GETDEVCAPS_PARMS   * PMCI_GETDEVCAPS_PARMS;
  

• If string data is returned, the second and third fields of the data structure are reserved for the return data. The second ULONG is assigned to a field reserved for a pointer to the null-terminated return string. The third ULONG is assigned to a field reserved for the size of return buffer. The application is responsible for creating the buffer for return string. Any data fields for passing information to the MCD start in the fourth field. For example, the MCI_INFO_PARMS structure shown in the following example uses pszReturn and ulRetSize for the return fields.

  typedef struct _MCI_INFO_PARMS {
      HWND      hwndCallback;  /* PM window handle for MCI notify message */
      PSZ       pszReturn;     /* Pointer to return buffer                */
      ULONG     ulRetSize;     /* Return buffer size                      */
  } MCI_INFO_PARMS;
  typedef MCI_INFO_PARMS   *PMCI_INFO_PARMS;
  

• If RECTL data is returned, the second through fifth fields of the data structure are reserved for the return data. The first ULONG position is reserved for the left values of the RECTL data. The second ULONG position is reserved for the bottom values of the RECTL data. Any data fields for passing information to the device driver start in the sixth ULONG position. Rather than specifying two ULONGs for the RECTL data, most data structure definitions use one RECTL data field to obtain an equivalent data structure. For example, the MCI_VID_RECT_PARMS structure shown in the following example uses rc for the return field.

  typedef  struct _MCI_VID_RECT_PARMS {
      HWND    hwndCallback;    /* PM window handle for MCI notify message */
      RECTL   rc;              /* rectangle array specifying the offset   */
                               /* and size of a rectangle                 */
  } MCI_VID_RECT_PARMS;