Reference for RetroPlatformIPC.h (RP Player interprocess communication include file)


****************************************************************************
 Guest-to-Host Messages
****************************************************************************

Message:
   RPIPCGM_REGISTER
Description:
   this is a private message and is automatically sent
   by the RPInitializeGuest() function
   to register the caller as a RetroPlatform guest


Message:
   RPIPCGM_FEATURES
Description:
   the guest uses this message to tell the host
   about the features it supports;
   at startup time, the guest sends initialization messages
   so that the host can adapt the GUI based on the reported features;
   these messages include:
      RPIPCGM_FEATURES (describes guest features),
      RPIPCGM_POWERLED (turns on the power LED in the GUI),
      RPIPCGM_DEVICES (one for each device category: tells the number of emulated devices),
      RPIPCGM_DEVICECONTENT (one for each device with an image file or peripheral attached),
      RPIPCGM_TURBO (tells if some of the turbo modes are activated from the start),
      RPIPCGM_VOLUME (reports about starting volume level),
      RPIPCGM_SCREENMODE (communicates the screen mode, the clipping coordinates and the guest window handle);
   note that at startup time the guest should create a borderless and hidden window
   and send its handle using a RPIPCGM_SCREENMODE message, which must be the last
   of the initialization messages, since it displays the guest window
   and the host "frame window" (the part of the player user interface
   with command and status icons which can be used to drag the guest window, etc.)
Data sent:
   WPARAM = RP_FEATURE_* flags
Response:
   none


Message:
   RPIPCGM_CLOSED
Description:
   this message is sent to the host when the guest is terminating
Data sent:
   none
Response:
   none


Message:
   RPIPCGM_ACTIVATED
Description:
   the guest sends this message to the host
   when its window is being activated
Data sent:
   LPARAM = identifier of the thread that owns the window being deactivated
Response:
   none


Message:
   RPIPCGM_DEACTIVATED
Description:
   the guest sends this message to the host
   when its window is being deactivated
Data sent:
   LPARAM = identifier of the thread that owns the window being activated
Response:
   none


Message:
   RPIPCGM_ENABLED
Description:
   the guest sends this message to the host when its window is being enabled
   (e.g. a WM_ENABLE message has been received with wParam set to TRUE);
   this usually occurs when closing a modal dialog (with guest's window as parent)
Data sent:
   none
Response:
   none


Message:
   RPIPCGM_DISABLED
Description:
   the guest sends this message to the host when its window is being disabled
   (e.g. a WM_ENABLE message has been received with wParam set to FALSE);
   this usually occurs when opening a modal dialog (with guest's window as parent)
Data sent:
   none
Response:
   none


Message:
   RPIPCGM_SCREENMODE
Description:
   the guest sends a RPIPCGM_SCREENMODE message to notify the host
   about a change in its "screen mode"
   (1x/2x/3x/4x, full screen, clipping coordinates, etc.),
   or to keep the host updated about the guest window handle
   (just before destroying its window, the guest sends this message
   with the hGuestWindow field of the RPSCREENMODE structure set to NULL);
   screen mode changes requested by the host
   (see the RPIPCHM_SCREENMODE message) must not be notified,
   unless this is an asynchronous screen mode change
   (i.e. the guest returned the INVALID_HANDLE_VALUE
   response to a RPIPCHM_SCREENMODE host request);
   at startup-time, the guest must create
   a borderless and hidden window and send its handle
   using this message; the host will then take care
   of preparing, positioning and showing the guest window
Data sent:
   pData = a RPSCREENMODE structure
Response:
   none


Message:
   RPIPCGM_POWERLED
Description:
   sent to the host to change the power LED state
Data sent:
   WPARAM = power LED intensity (min/off 0, max 100)
Response:
   none


Message:
   RPIPCGM_DEVICES
Description:
   this message is used to notify the host about a change
   in the number of emulated devices (floppy drives, hard disks, etc.)
Data sent:
   WPARAM = device category (RP_DEVICE_* value)
   LPARAM = 32-bit bitfield representing the devices
            emulated in the specified category
            (every bit set to 1 corresponds to a mounted drive
             e.g. 0x00000005 = drive 0 and drive 2 are emulated)
Response:
   none


Message:
   RPIPCGM_DEVICEACTIVITY
Description:
   this message can be used to turn on or off the activity indicator
   of a specified device (like a LED on the original hardware);
   the indicator can also be "blinked", i.e. the host will turn the
   LED on and then off again after the specified amount of time
Data sent:
   WPARAM = device category (RP_DEVICE_* value) and device number
            combined with the MAKEWORD macro;
            e.g. MAKEWORD(RP_DEVICE_FLOPPY, 0);
            the RP_ALL_DEVICES define may be used as device number
            to turn on or off all the activity leds for a device category
   LPARAM = led status and flags combined with the MAKEWORD macro;
            e.g. MAKEWORD(Status, Flags);
            the Status value can be set to 0 to turn off the activity LED,
            or set to -1 to turn on the activity LED,
            or set to a <millisecond delay> value to turn on the activity LED
            for the specified amount of time (blink);
            the Flags value can be set
            using one of the RP_DEVICEACTIVITY_* defines
Response:
   none


Message:
   RPIPCGM_MOUSECAPTURE
Description:
   the guest sends this message when the mouse is captured/released
   (the mouse is "captured" when its movements are restricted to the guest window area
   and the system cursor is not visible);
   mouse capture changes requested by the host
   (see the RPIPCHM_MOUSECAPTURE message) must not be notified;
   for consistency across different guests, a guest which sends RPIPCGM_MOUSECAPTURE
   messages should also implement a keyboard-actuated escape functionality
   (the preferred key for this purpose is included in the parameters sent from the
   host at startup time - see RPLaunchGuest() in RetroPlatformPlugin.h);
   note that in order not to interfere with the window dragging functionality,
   the mouse should not be captured when the guest window gets the focus,
   but when a mouse button event is received
Data sent:
   WPARAM = mouse capture state (RP_MOUSECAPTURE_* flags)
            four possible states are currently possible
            (i.e. the mouse can be captured or not
             and the magic mouse feature can be active or not)
Response:
   none


Message:
   RPIPCGM_HOSTAPIVERSION
Description:
    the guest can send a RPIPCGM_HOSTAPIVERSION to query the host
    about the RetroPlatform API version it implements;
    since the guest plugin already asks for a minimim version of the API
    on the host side, this message can be used to check the host API version
    and enable optional functionality
Data sent:
   none
Response:
   LRESULT = major and minor version combined with the MAKELONG macro
             (e.g. LOWORD(lr) = major version; HIWORD(lr) = minor version)


Message:
   RPIPCGM_PAUSE
Description:
   the guest sends this message to the host
   when it enters or exits pause mode;
   pause mode changes requested by the host
   (see the RPIPCHM_PAUSE message) must not be notified,
   unless the guest returned the value 2 as RPIPCHM_PAUSE response;
   note: when paused, the guest should release the mouse (if captured);
   during pause moude, the mouse should never be captured
Data sent:
   WPARAM = non-zero when the guest enters pause mode
            or zero when the guest exits from pause mode
Response:
   none


Message:
   RPIPCGM_DEVICECONTENT
Description:
   the guest sends a RPIPCGM_DEVICECONTENT message
   to notify the host that an image file (e.g. a floppy disk image)
   or a peripheral (e.g. a joystick)
   has been loaded into (or ejected from) an emulated device;
   this notification must not be sent when the event
   has been requested by the host (see the RPIPCHM_DEVICECONTENT message)
Data sent:
   pData = a RPDEVICECONTENT structure (see RetroPlatformIPC.h);
           the szContent field of the structure
           contains an empty string when the guest
           is ejecting something from the device
Response:
   none


Message:
   RPIPCGM_TURBO
Description:
   the guest sends a RPIPCGM_TURBO message
   to notify the host about activation of "turbo" (maximum speed) mode
   of some of its functionalities (e.g. floppy, CPU);
   turbo mode activations/deactivations requested by the host
   (see the RPIPCHM_TURBO message) must not be notified;
Data sent:
   WPARAM = mask of functionalities affected (RP_TURBO_* flags)
   LPARAM = bits corresponding to those set in WPARAM
            (1 = turbo mode activated for the guest functionality
             0 = guest functionality reverted to normal speed)
Response:
   none


Message:
   RPIPCGM_PING
Description:
   this is a no-operation message and can be sent
   to check if the host is responsive and functional
Data sent:
   none
Response:
   LRESULT = non-zero value is returned


Message:
   RPIPCGM_VOLUME
Description:
   the guest uses the RPIPCGM_VOLUME message
   to notify the host about a change of its audio level;
   audio level changes requested by the host
   (see the RPIPCHM_VOLUME message) must not be notified
Data sent:
   WPARAM = volume level (min/off 0, max 100)
Response:
   none


Message:
   RPIPCGM_ESCAPED
Description:
   this message is sent to notify the host
   that the escape key has been held down
Data sent:
   none
Response:
   none


Message:
   RPIPCGM_PARENT
Description:
   the guest sends this message to the host to get the handle
   of the parent for its window; the guest window must be created
   as a borderless (WS_POPUP style), hidden window,
   using the handle returned by this message as the parent window parameter
Data sent:
   none
Response:
   LRESULT = window handle (HWND) to use in a CreateWindow call


Message:
   RPIPCGM_DEVICESEEK
Description:
   this message can be used to notify the host about a seek operation
   of a specified device (e.g. the head of a disk drive changes position);
Data sent:
   WPARAM = device category (RP_DEVICE_* value) and device number
            combined with the MAKEWORD macro;
            e.g. MAKEWORD(RP_DEVICE_FLOPPY, 0)
   LPARAM = device-dependant seek position (e.g. drive track position)
Response:
   none


Message:
   RPIPCGM_CLOSE
Description:
   when the user presses ALT+F4 in the guest window
   the guest should intercept such an event
   (WM_SYSCOMMAND with wParam set to SC_CLOSE),
   send this notification message to the host
   and not close its window (i.e. not call the DefWindowProc() of its window);
   the host will then open its Close Options dialog
   and will send a RPIPCHM_CLOSE command to the guest
   if the user confirms the close request
Data sent:
   none
Response:
   none




****************************************************************************
 Host-to-Guest Messages
****************************************************************************

Message:
   RPIPCHM_CLOSE
Description:
   sent from the host when the emulation must be terminated
   (e.g. the user has hit the close button in the host window);
   the guest should destroy its window and terminate (see Response below)
Data sent:
   none
Response:
   LRESULT = 1 if the guest can safely terminate or 0 otherwise


Message:
   RPIPCHM_SCREENMODE
Description:
   this message is sent to ask the guest to activate a specified screen mode
   and clipping coordinates;
   when switching to the new screen mode, the guest can resize (reuse) its window
   or close its window and open a new one;
   if output to a secondary display is requested, and only one
   display is available, or more than two displays are available,
   it is up to the guest to gracefully choose a display
Data sent:
   pData = a RPSCREENMODE structure, with screen mode values/flags
   and clipping coordinates (the hGuestWindow field is ignored);
   as regards the clipping coordinates, the fields set to 0 mean "reset"
   (no offset for lClipLeft/lClipTop, maximum size if lClipWidth/lClipHeight)
   and fields set to -1 are ignored (left unchanged); units are in pixels;
   for Amiga systems, where pixels may have different sizes, horizontal
   units are in superhires pixels (4 x lores) for Amiga modes, and
   vertical units are in interlaced pixels (2 x non-interlaced), whereas
   RTG pixels are always 1:1
Response:
   LRESULT = handle of the (new) guest window
             or NULL (the screen mode couldn't be changed)
             or INVALID_HANDLE_VALUE (the screen mode will be changed asynchronously
             and the host will soon get a RPIPCGM_SCREENMODE notification)


Message:
   RPIPCHM_SCREENCAPTURE
Description:
   with this message the host asks the guest to save its screen
   to the the specified file in BMP format
Data sent:
   pData = (Unicode) full path and name of the file to save
           (note: the file may exist and can be overwritten)
Response:
   LRESULT = 1 if the guest successfully saved its screen to the file or 0 otherwise


Message:
   RPIPCHM_PAUSE
Description:
   the RPIPCHM_PAUSE message sets the guest into pause mode
   or resumes the guest from pause mode;
   note: when paused, the guest should release the mouse (if captured);
   during pause moude, the mouse should never be captured
Data sent:
   WPARAM = non-zero to set the guest into pause mode
            or zero to resume the guest from pause mode
Response:
   LRESULT = 0 (error), 1 (command successfully executed)
             or 2 (the command will be asynchronously executed
             and a RPIPCGM_PAUSE will be later sent from the guest
             to confirm execution)


Message:
   RPIPCHM_DEVICECONTENT
Description:
   the host sends a RPIPCHM_DEVICECONTENT message
   to load an image file or a peripheral into an emulated device
   (e.g. an ADF floppy file into a floppy drive,
   or a physical or keyboard-emulated joystick into an input port)
   or to unload the currently loaded content from the device
Data sent:
   pData = a RPDEVICECONTENT structure (see RetroPlatformIPC.h);
           if the szContent field of the structure
           contains an empty string, the guest should
           unload the current content from the device;
           for joysticks, szContent may contain multiple identifiers
           using the "Joystick1\ProductGUID\ProductName" format
           (ProductName is last and may contain unescaped backslash
           characters itself)
Response:
   LRESULT = 1 if the guest successfully executed the command or 0 otherwise


Message:
   RPIPCHM_RESET
Description:
   the host sends this message to reset the guest
Data sent:
   WPARAM = a RP_RESET_* value
Response:
   LRESULT = 1 if the guest successfully executed the command or 0 otherwise


Message:
   RPIPCHM_TURBO
Description:
   the host sends this message to activate or deactivate
   the turbo mode of selected guest functionalities
Data sent:
   WPARAM = mask of functionalities to change (RP_TURBO_* flags)
   LPARAM = bits corresponding to those set in WPARAM
            (1 = speedup the guest functionality
             0 = revert to normal speed emulation)
Response:
   LRESULT = 1 if the guest successfully executed the command or 0 otherwise


Message:
   RPIPCHM_PING
Description:
   this is a no-operation message and can be sent
   to check if the guest is responsive and functional
Data sent:
   none
Response:
   LRESULT = non-zero value is returned


Message:
   RPIPCHM_VOLUME
Description:
   the host uses the RPIPCHM_VOLUME message to set
   the audio level of the guest
Data sent:
   WPARAM = volume level (min 0, max 100)
Response:
   LRESULT = 1 if the guest successfully set the volume as requested or 0 otherwise


Message:
   RPIPCHM_ESCAPEKEY
Description:
   the host uses the RPIPCHM_ESCAPEKEY message
   to change the escape key information
Data sent:
   WPARAM = DirectInput DIK_* identifier of the escape key
            (e.g. 1 for the Esc key - see DIK_* constants in dinput.h)
   LPARAM = milliseconds value
            (amount of time the user has to hold the above key to trigger the escape functionality)
Response:
   LRESULT = 1 if the guest successfully accepted the new settings or 0 otherwise


Message:
   RPIPCHM_EVENT
Description:
   the host uses the RPIPCHM_EVENT message
   to simulate keyboard, mouse, joystick (press/release)
   and other guest-specific events
Data sent:
   pData = (Unicode) event string (guest-specific)
Response:
   LRESULT = 1 if the guest successfully simulated the specified event or 0 otherwise


Message:
   RPIPCHM_MOUSECAPTURE
Description:
   the host uses this message to ask the guest
   to capture or release the mouse (and activate/deactivate the magic mouse functionality)
Data sent:
   WPARAM = mouse capture state being requested (RP_MOUSECAPTURE_* flags)
Response:
   LRESULT = 1 if the guest successfully executed the command or 0 otherwise


Message:
   RPIPCHM_SAVESTATE
Description:
   with this message the host asks the guest to save
   the emulation status to the the specified file
Data sent:
   pData = (Unicode) full path and name of the file to save
Response:
   LRESULT = 1 if the guest successfully saved the status file or 0 otherwise


Message:
   RPIPCHM_LOADSTATE
Description:
   with this message the host asks the guest to load
   the emulation status from the the specified file
Data sent:
   pData = (Unicode) full path and name of the file to load
Response:
   LRESULT = 1 if the guest successfully loaded the status file or 0 otherwise
