PORTABLE AUDIO DEVICE SDK

Portable Device SDK

(last updated February 5, 2002)

Overview

Portable Devices are accessed from Media Jukebox (MJ) through a Plug-in that is created for each device. The Plug-in is an ATL COM object that includes a set of functions that are the interface to Media Jukebox. MJ interacts with the Plug-in through a ListControl (RightView) that displays file information from the Device and a TreeControl(LeftTree) that displays storage folder information. These controls are not accessed directly by the Plug-in. The necessary data exchange for these controls is handled via the following functions.

MJ Plug-in Functions:

Initialize( [in] BSTR bstrPath, [out] BSTR * bstrMemoryTypes, [out] BSTR * bstrRClickMenuItems, [out, retval] LONG *pError)

Description: Initialize() is called from MJ until it returns with a pError value of 0, the default. It is used to make sure the player is connected and ready to communicate with MJ.

Parameters:
bstrPath - The Devicename or Driveletter that is recognized by MJ
bstrMemoryTypes - A “|” delimited string of the memory types supported by the device.
bstrRClickMenuItems - The rightclick menu items for the RightView to be handled by the Plug-in. Options include Delete, Rename, and Add. These can be named whatever but the first item will send a IDM_HH_MENU_ITEM_DELETE to MJ when selected. The second item will send IDM_HH_MENU_ITEM_RENAME and the third item will send IDM_HH_MENU_ITEM_ADD.
pError - Set to TRUE if there is an error. FALSE alerts MJ to call “GetLastError” to display an error message and causes MJ to take action where appropriate.

GetColumnInfo( [in] BSTR bstrPathInfo, [out] BSTR *bstrFieldInfo, [out, retval] LONG *pError)

Description: GetColumnInfo() is called whenever the RightView is updated. It creates the appropriate columns in RightView to be populated by StoreFileInfo / GetFileInfo.

Parameters:
bstrPathInfo - A “|” delimited path from the LeftTree. This path dictates what columns should be displayed.
bstrFieldInfo – A “|” delimited string of any of column names.

pError - Set to TRUE if there is an error. FALSE alerts MJ to call “GetLastError” to display an error message and causes MJ to take action where appropriate.

GetTreeItem( [in] BSTR bstrPath, [out] BSTR *pItem, [out] LONG * pHasChildren, [out, retval] LONG * pStopRecursion)

Description: GetTreeItem() is a recursive function that is called to populate LeftTree.

Parameters:
bstrPath - A “|” delimited path from LeftTree .
pItem – A “|” delimited path of the subfolders of the path in bstrPath.
pHasChildren – Set to TRUE if bstrPath can have children.
pStopRecursion – Set to TRUE if there are no items to display.

StoreFileInfoForRetrieval( [in] BSTR bstrPath, [out] LONG *pColumnReorderSupport, [out] LONG *pEnableInPlaceEditing, [out, retval] LONG *pError)

Description: StoreFileInfoForRetrieval() is called prior to calls to GetFileInfo. This function alerts the Plug-in that it should store the necessary data for the GetFileInfo calls.

Parameters:
bstrPath - A “|” delimited path from LeftTree. Files that are in this path should be stored.
pColumnReorderSupport - TRUE alerts MJ that the RightView associated with this LeftTree path supports Track Reordering. Otherwise “FALSE”.
pEnableInPlaceEditing – TRUE alerts MJ that the RightView associated with this LeftTree path supports in place track editing. Otherwise “FALSE”.
pError - Set to TRUE if there is an error. FALSE alerts MJ to call “GetLastError” to display an error message and causes MJ to take action where appropriate.

GetFileInfo( [in] LONG lIndex, [out] BSTR *bstrFileInfo, [out] LONG *pIsLastFile, [out, retval] LONG *pError)

Description: GetFileInfo() is called for each file to be displayed in RightView for the path that was specified in StoreFileInfo() with the information that was specified in GetColumnInfo().

Parameters:
lIndex - The index of the file information requested by MJ
bstrFileInfo – A “;” delimited string of file information for bstrPath from StoreFileInfo() with data from bstrFieldInfo from GetColumnInfo().
pIsLastFile – TRUE if there are no more files to display else FALSE
pError - Set to TRUE if there is an error. FALSE alerts MJ to call “GetLastError” to display an error message and causes MJ to take action where appropriate.

GetMemoryInfo( [in] BSTR bstrPath, [out] LONGLONG *pTotalSize, [out] LONGLONG *pAvailableSize, [out, retval] LONG *pError)

Description: GetMemoryInfo() returns the total and available size for a memory type that is defined in bstrMemoryTypes during Initialize().

Parameters:
bstrPath - A “\” delimited path from the LeftTree. This path dictates what memory information should be displayed.
pTotalSize – Total size of the selected memory type.
pAvailableSize - Available size of the selected memory type.
pError - Set to TRUE if there is an error. FALSE alerts MJ to call “GetLastError” to display an error message and causes MJ to take action where appropriate.

ShowMenu( [in] BSTR bstrPath, [out, retval] LONG *pError)

Description: ShowMenu() handles right click functionality for LeftTree. It is called when a RightClick is performed on a LeftTree branch of a Device Plug-in.

Parameters:
bstrPath - A “\” delimited path from the LeftTree. This path dictates what RightClick options should be displayed.
pError - Set to TRUE if there is an error. FALSE alerts MJ to call “GetLastError” to display an error message and causes MJ to take action where appropriate.

ProcessCommand( [in] BSTR bstrFileInfo, [in] LONG lCommand, [out] BSTR * pItem, [out, retval] LONG * pError)

Description: ProcessCommand() is called to handle a variety of MJ defined tasks

Parameters:
bstrFileInfo – Command specific data coming to the Plug-in from MJ.
lCommand – One of the commands detailed in Examples.
pItem – A variable for returning command specific data to MJ.
pError - Set to TRUE if there is an error. FALSE alerts MJ to call “GetLastError” to display an error message and causes MJ to take action where appropriate.

Examples:

Required commands received from MJ:

IDM_HH_UPLOAD is sent when MJ attempts to send files to the Device.

bstrFileInfo [in] – A “|” delimited string of files to upload to the Device. All files to upload are sent in this one string. The data is in the following form:
COUNT|HH_Location|Location|Name|Artist|Album|Genre|Comment|TrackNumber|Year|FileSize|Duration|

COUNT is the count of how many fields of data will follow. COUNT is only sent at the beginning of the string. All other fields repeat for multiple files. HH_Location is the path where the file will go on the device. Location is the current file location.

pItem [out] – Not used.

IDM_HH_GET_DEFAULT_LOCATION is called during Initialization and is MJ’s way of storing a default location on the device to put files when using MJ’s SendTo functionality.

pItem [out] – Return to MJ the default path for file uploads from MJ to the device (i.e. “Player\\Internal Memory\\Folder1\\”).

Optional commands received from MJ:

IDM_HH_MENU_ITEM_DELETE is sent to notify the Device to remove certain files.

bstrFileInfo [in] - A “|” delimited string of paths to files on the Device that need to be deleted (i.e. “MyPlayer\Folder1\File1|MyPlayer\Folder2\File2|”)
pItem [out] – Not used.

IDM_HH_MENU_ITEM_RENAME will be sent to request that a file on the Device change a particular name of some stored data.

bstrFileInfo [in] – A “|” delimited string in the following format – “HH_FIELD_NAME|HH_FIELD_LOCATION|NewData”
where HH_FIELD_NAME is the column name of the field to modify (as passed to MJ from GetColumnInfo()) HH_FIELD_LOCATION is the path to which file on the Device should be modified and NewData is the new name for the selected field.

IDM_HH_MENU_ITEM_ADD can be used to add files to folders or other tasks.

bstrFileInfo [in] – A “|” delimited string of full paths to files on the Device.

IDM_HH_REORDER_FILES will be sent if the pColumnReorderSupport flag in StoreFileInfoForRetrieval() is set.

bstrFileInfo [in] – A “|” delimited string in the form “PATH|FILENAME|FILENAME”
where PATH is the LeftTree view that is displayed by MJ in the form “Device\\Memory\\Folder” and FILENAME is a list of the new order of the files as they are to be arranged on the Device.

Optional commands sent to MJ from the Device Plug-in:

The following commands should be used as part of a call to MJ using
Fire_SendMJMessage(LONG lMessage, LONG lParam1, LONG lParam2, LONG *pInfo,BSTR bstrFileInfo)

HH_UPDATE_MJ - The lMessage variable for HH_REBUILD_LEFT_TREE and HH_UPDATE_RIGHT_VIEW.

HH_REBUILD_LEFT_TREE - Set lMessage to HH_UPDATE_MJ and lParam1 to HH_REBUILD_LEFT_TREE to cause MJ to refresh LeftTree.

HH_UPDATE_RIGHT_VIEW - Set lMessage to HH_UPDATE_MJ and lParam1 to HH_UPDATE_RIGHT_VIEW to refresh RightView.

HH_SET_STATUS_TEXT - To show file transfer status during uploads, set lMessage to HH_SET_STATUS_TEXT and bstrFileInfo to the appropriate dialog text to inform users what is being transferred. (i.e. “Currently uploading file 1”)

HH_SET_PROGRESS - To show file upload progress, set lMessage to HH_SET_PROGRESS, lParam1 to the percent of the current file that has transferred, and lParam2 to the percent of the total files being transferred currently completed. pInfo is a flag that is passed to MJ. If pInfo is non-zero, it indicates that file transfers should be cancelled. bstrFileInfo is the file name being transferred.

HH_UPDATE_AFTER_UPLOAD - Set lMesssage to HH_UPDATE_MJ and lParam1 to HH_UPDATE_AFTER_UPLOAD when all uploads are complete to tell MJ to redraw LeftTree and RightView.

GetIsItemDropable([in] BSTR bstrPath, [out] LONG * pIsDropable, [out, retval] LONG * pError)

Description: GetIsItemDropable() is called as a drag and drop file passes over a LeftTree item related to a Device Plug-in.

Parameters:
bstrPath – A “|” delimited path of where in LeftTree the file is currently passing over.
pIsDropable - Set to True if this is an acceptable drop path, False if not. MJ will allow or disallow dropping files on this path based on this value.
pError - Set to TRUE if there is an error. FALSE alerts MJ to call “GetLastError” to display an error message and causes MJ to take action where appropriate.

Close( [out, retval]LONG *pError)

Description: Close() is called before the final closing of MJ. Close() should be used for any necessary cleanup of the Plug-in before disconnection from MJ

Parameters:
pError - Set to TRUE if there is an error. FALSE alerts MJ to call “GetLastError” to display an error message and causes MJ to take action where appropriate.

GetLastError( [out]BSTR *pError)

Description: GetLastError() is called whenever the pError flag is set to TRUE in any other Plug-in function call.

Parameters:
pError – Set this to the error message MJ should display.

Apendix A

Sample code to be inserted in the Plug-in’s DllRegisterServer() and DllUnregisterServer() calls.

#define REGISTRY_PATH_MJ_PLUGINS_HH "Software\\J. River\\Music Exchange\\1.0\\Media Jukebox\\Plugins\\Handheld\\"

STDAPI DllRegisterServer(void)
{

char RegistryPath[1024];
char strName[128] = {"Insert Playername Here"};
strcpy(RegistryPath, REGISTRY_PATH_MJ_PLUGINS_HH);
strcat(RegistryPath, strName);

CRegKey reg;
if(ERROR_SUCCESS == reg.Create(HKEY_LOCAL_MACHINE, RegistryPath))
{

// general plugin information
DWORD nIVersion = 5; // Must be set to 5 for version 8 MJ
char strCompany[128] = {"Your Company Name"};
char strVersion[10] = {"A version number"};
char strURL[128] = {“Your URL"};
char strCopyright[255] = {"A Copyright message"};

LPWSTR strID;
StringFromCLSID(CLSID_YourCLSID, &strID);
reg.SetValue(_bstr_t(strID), "CLSID");

StringFromCLSID(IID_IYourIID, &strID);
reg.SetValue(_bstr_t(strID), "IID");

StringFromCLSID(IID__IYourImplEvents, &strID);
reg.SetValue(_bstr_t(strID), "EIID");

reg.SetValue(nIVersion, "IVersion");
reg.SetValue(strCompany, "Company");
reg.SetValue(strVersion, "Version");
reg.SetValue(strURL, "URL");
reg.SetValue(strCopyright, "Copyright");

// hand held specific options
DWORD nSupportedOS = PLATFORM_WINDOWS_9X|PLATFORM_WINDOWS_2000|PLATFORM_WINDOWS_ME|PLATFORM_WINDOWS_XP;
DWORD nPorts = HANDHELDPORT_USB;
char strMediaTypes[128] = {"mp3,wma,wav"};
reg.SetValue(nSupportedOS, "SupportedOS");
reg.SetValue(strMediaTypes, "MediaTypes");
reg.SetValue(nPorts, "Ports");

}
return _Module.RegisterServer(TRUE);

}

/////////////////////////////////////////////////////////////////////////////
// DllUnregisterServer - Removes entries from the system registry

STDAPI DllUnregisterServer(void)
{

char RegistryPath[1024];
strcpy(RegistryPath, REGISTRY_PATH_MJ_PLUGINS_HH);
strcat(RegistryPath, "Insert Playername here");

RegDeleteKey(HKEY_LOCAL_MACHINE, RegistryPath);
return _Module.UnregisterServer(TRUE);

}

If you have questions or concerns not addressed by this SDK, or just have suggestions for making the SDK more understandable, please visit our developer's forum