MJFileAutomation: Difference between revisions

From wiki.jriver.com
Jump to navigation Jump to search
No edit summary
 
No edit summary
 
(9 intermediate revisions by 5 users not shown)
Line 2: Line 2:
==Functions==
==Functions==
===MJPlaylistsAutomation * GetPlaylists()===
===MJPlaylistsAutomation * GetPlaylists()===
'''Description:''' returns the collection of playlists that the given file is in<br>
'''Description:''' returns an [[MJPlaylistsAutomation]] interface containing the collection of playlists that the given file is in<br>
'''Return Value:''' MJPlaylistsAutomation interface (see below)
'''Return Value:''' [[MJPlaylistsAutomation]] interface


===string GetImageFile(MJImageFileFlags nImageFileFlag)===
===string GetImageFile(MJImageFileFlags nImageFileFlag)===
Line 15: Line 15:
** IMAGEFILE_DISPLAY_NO_DEFAULT - like IMAGEFILE_DISPLAY except that it won't return the logo when there is no art
** IMAGEFILE_DISPLAY_NO_DEFAULT - like IMAGEFILE_DISPLAY except that it won't return the logo when there is no art
** IMAGEFILE_DISPLAY_NO_DEFAULT_STANDARD_JPEG - like IMAGEFILE_DISPLAY_NO_DEFAULT except that it always returns a standard (non-progressive) JPEG
** IMAGEFILE_DISPLAY_NO_DEFAULT_STANDARD_JPEG - like IMAGEFILE_DISPLAY_NO_DEFAULT except that it always returns a standard (non-progressive) JPEG
** IMAGEFILE_THUMBNAIL_BINARY - all three thumbnails stored in a single file. Used by Library Server.
Note: Do not delete the files returned by this function. Media Center will do any necessary cleanup. Also, subsequent calls may return the same filename (if a temp file is being used) so you must load / cache the image instead of caching the filenames.
Note: Do not delete the files returned by this function. Media Center will do any necessary cleanup. Also, subsequent calls may return the same filename (if a temp file is being used) so you must load / cache the image instead of caching the filenames.
'''Return Value:''' a filename of the image file
'''Return Value:''' a filename of the image file


===string SetImageFile(string strImageFile, MJImageFileFlags nImageFileFlag)===
===string SetImageFile(string strImageFile, MJImageFileFlags nImageFileFlag)===
Line 22: Line 23:
'''Parameters:'''
'''Parameters:'''
* '''strImageFile''': filename of the image
* '''strImageFile''': filename of the image
* '''nImageFileFlag''':
* '''nImageFileFlag''': IMAGEFILE_IN_DATABASE - database image, IMAGEFILE_IN_FILE - tag image (stored inside of file)
** IMAGEFILE_IN_DATABASE - database image<br>''Image is saved in DB and in file (maybe this depends on the used JRMC settings). However the image file is not saved to the folder set in the options (e.g. with track or in a special cover image folder). This has to be done with separate code.''
'''Return Value:''' 0 on failure, non-zero on success
** IMAGEFILE_IN_FILE - tag image (stored inside of file)<br>''This doesn't seem to work as images are not saved to the file.''
'''Return Value (bool):''' false (0) on failure, true (non-zero) on success


===string GetFormattedFileSize()===
===string GetFormattedFileSize()===
Line 43: Line 46:
===string GetAvailableFilename()===
===string GetAvailableFilename()===
'''Description:''' returns the filename in the format that's available to the system, so that files on a removable device get returned, for example, as "D:\1.mp3" instead of "(0xF43EA231):\1.mp3"<br>
'''Description:''' returns the filename in the format that's available to the system, so that files on a removable device get returned, for example, as "D:\1.mp3" instead of "(0xF43EA231):\1.mp3"<br>
'''Return Value:''' a string representing the filename

===string GetFilenameEx(int, int)===
'''Return Value:''' a string representing the filename
'''Return Value:''' a string representing the filename


Line 53: Line 59:
'''Parameters:'''
'''Parameters:'''
* '''strField''': name of the field (e.g. Artist, Album...)
* '''strField''': name of the field (e.g. Artist, Album...)
* '''bFormatted''': determines whether the return value should beformated.
* '''bFormatted''': determines whether the return value should be formatted.
'''Return Value:''' value of the field
'''Return Value:''' value of the field


===boolean Set(string strField, string strValue)===
===boolean Set(string strField, string strValue)===
Line 64: Line 70:


===MJFilesAutomation * GetAlbumFiles()===
===MJFilesAutomation * GetAlbumFiles()===
'''Description:''' retrieves the list of files which belong to the same album (use to expand after an album group)<br>
'''Description:''' returns an [[MJFilesAutomation]] interface containing the list of files which belong to the same album (use to expand after an album group)<br>
'''Return Value:''' MJFilesAutomation interface
'''Return Value:''' [[MJFilesAutomation]] interface


===long GetKey()===
===int GetKey()===
'''Description:''' Gets the key of the file<br>
'''Description:''' Gets the key of the file<br>
'''Return Value:''' the key
'''Return Value:''' the key


===boolean DeleteFile(long hwndParent)===
===boolean DeleteFile(long hwndParent)===
Line 90: Line 96:


===boolean SilentDeleteFile()===
===boolean SilentDeleteFile()===
'''Description:''' Deletes the file (no confirmation)<br>
'''Description:''' Deletes the file (no confirmation). Remark: This rather removes the file from the database, but does not delete the file on disc.<br>
'''Return Value:''' nonzero on success, zero on failure
'''Return Value:''' nonzero on success, zero on failure


===void UpdatePlaybackStats(long nPlays)===
===void UpdatePlaybackStats(long nPlays)===
Line 135: Line 141:
* '''strField''': the field name
* '''strField''': the field name
* '''strValue''': the field value
* '''strValue''': the field value
'''Return Value:''' nonzero on success, zero on failure
'''Return Value:''' nonzero on success, zero on failure


==Properties==
==Properties==
Line 202: Line 208:


===string AlbumArtist() (read / write)===
===string AlbumArtist() (read / write)===
'''Description:''' the album artist<br>
'''Description:''' the album artist (auto) ''(to get the real field value of album artist use: <tt>Get("Album Artist", false)</tt>)''<br>

[[Category:COM Automation]]

Latest revision as of 05:38, 4 May 2015

MJFileAutomation - object for dealing with a single file

Functions

MJPlaylistsAutomation * GetPlaylists()

Description: returns an MJPlaylistsAutomation interface containing the collection of playlists that the given file is in
Return Value: MJPlaylistsAutomation interface

string GetImageFile(MJImageFileFlags nImageFileFlag)

Description: gets the filename of an image associated with the file
Parameters:

  • nImageFileFlag:
    • IMAGEFILE_DISPLAY - display image (tag or database) (uses MJ logo if file doesn't have an image)
    • IMAGEFILE_IN_DATABASE - database image
    • IMAGEFILE_IN_FILE - tag image (stored inside of file)
    • IMAGEFILE_THUMBNAIL_SMALL, IMAGEFILE_THUMBNAIL_MEDIUM, IMAGEFILE_THUMBNAIL_LARGE - small, medium, and large thumbnail images for the file
    • IMAGEFILE_DISPLAY_NO_DEFAULT - like IMAGEFILE_DISPLAY except that it won't return the logo when there is no art
    • IMAGEFILE_DISPLAY_NO_DEFAULT_STANDARD_JPEG - like IMAGEFILE_DISPLAY_NO_DEFAULT except that it always returns a standard (non-progressive) JPEG
    • IMAGEFILE_THUMBNAIL_BINARY - all three thumbnails stored in a single file. Used by Library Server.

Note: Do not delete the files returned by this function. Media Center will do any necessary cleanup. Also, subsequent calls may return the same filename (if a temp file is being used) so you must load / cache the image instead of caching the filenames. Return Value: a filename of the image file

string SetImageFile(string strImageFile, MJImageFileFlags nImageFileFlag)

Description: sets the image for the file
Parameters:

  • strImageFile: filename of the image
  • nImageFileFlag:
    • IMAGEFILE_IN_DATABASE - database image
      Image is saved in DB and in file (maybe this depends on the used JRMC settings). However the image file is not saved to the folder set in the options (e.g. with track or in a special cover image folder). This has to be done with separate code.
    • IMAGEFILE_IN_FILE - tag image (stored inside of file)
      This doesn't seem to work as images are not saved to the file.

Return Value (bool): false (0) on failure, true (non-zero) on success

string GetFormattedFileSize()

Description: gets the display friendly file size
Return Value: a string representing the file size (i.e. "23.434 MB")

string GetFormattedFileDate()

Description: gets the display friendly file date / time
Return Value: a string representing the file date / time (i.e. "2/30/2002 8:01 PM")

string GetFormattedDuration()

Description: gets the display friendly duration
Return Value: a string representing the duration (i.e. "3:04")

string GetFormattedLastPlayed()

Description: gets the display friendly last played date / time
Return Value: a string representing the duration (i.e. "2/30/2002 8:01 PM")

string GetAvailableFilename()

Description: returns the filename in the format that's available to the system, so that files on a removable device get returned, for example, as "D:\1.mp3" instead of "(0xF43EA231):\1.mp3"
Return Value: a string representing the filename

string GetFilenameEx(int, int)

Return Value: a string representing the filename

boolean SaveToTag()

Description: Forces Media Center to save the file information to the tag.
Return Value: 0 - failed, 1 - success.

string Get(string strField, boolean bFormatted)

Description: generic function to get value for the specified field.
Parameters:

  • strField: name of the field (e.g. Artist, Album...)
  • bFormatted: determines whether the return value should be formatted.

Return Value: value of the field

boolean Set(string strField, string strValue)

Description: generic function to set value for the specified field.
Parameters:

  • strField: name of the field (e.g. Artist, Album...)
  • strValue: new value of the field

Return Value: 0 - failed, 1 - success.

MJFilesAutomation * GetAlbumFiles()

Description: returns an MJFilesAutomation interface containing the list of files which belong to the same album (use to expand after an album group)
Return Value: MJFilesAutomation interface

int GetKey()

Description: Gets the key of the file
Return Value: the key

boolean DeleteFile(long hwndParent)

Description: Deletes the file (with confirmation)
Parameters:

  • hwndParent: The handle of the parent window or null

Return Value: nonzero on success, zero on failure

boolean RotateImage(long nDegrees)

Description: If the file is a JPEG, rotate the image
Parameters:

  • nDegrees: How much to rotate

Return Value: TRUE

string GetFilledTemplate(string strTemplate)

Description: Evaluates an expresion for the file and returns the result
Parameters:

  • strTemplate: the expression

Return Value: the result

boolean SilentDeleteFile()

Description: Deletes the file (no confirmation). Remark: This rather removes the file from the database, but does not delete the file on disc.
Return Value: nonzero on success, zero on failure

void UpdatePlaybackStats(long nPlays)

Description: Increases the file playcount by nPlays and sets the last played time to now
Parameters:

  • nPlays: number of times the file was played

boolean SaveInfoToExternalFile(string strFilename)

Description: Save the database information (cover art and fields) for the file to an external file
Parameters:

  • strFilename: the name of the external file

Return Value: TRUE

boolean UpdateFromFile(boolean bForce, boolean bOnlyNewFields)

Description: Updates the fields from the file
Parameters:

  • bForce: if true, force the update, otherwise only update if the file has changed
  • bOnlyNewFields: Only change fields that are new

Return Value: TRUE only if the file was updated

void UpdateDBLocation(long nAppendDBLocations, long nRemoveDBLocations)

Description: Select which portions of the database the file appears in
Parameters:

  • nAppendDBLocations: Which portions to add the file to. Value is a bitwise OR of
    • DB_LOCATION_INVALID
    • DB_LOCATION_MAIN
    • DB_LOCATION_PLAYING_NOW
    • DB_LOCATION_CD
    • DB_LOCATION_EXPLORER
    • DB_LOCATION_UNASSIGNED
    • DB_LOCATION
    • DB_LOCATION_FILE_TRANSFER
    • DB_LOCATION_HANDHELD
    • DB_LOCATION_GROUPING
    • DB_LOCATION_REMOVED
    • DB_LOCATION_DOWNLOADING
    • DB_LOCATION_PODCAST_FEED
  • nRemoveDBLocations: Which portions to remove the file from, same value as nAppendDBLocations

boolean SetNoDirty(string strField, string strValue)

Description: Change a file's field without marking it as dirty
Parameters:

  • strField: the field name
  • strValue: the field value

Return Value: nonzero on success, zero on failure

Properties

string Filename() (read / write)

Description: the filename (i.e. "c:\Music\Good Song.mp3")

string Artist() (read / write)

Description: the artist (i.e. "Metallica")

string Album() (read / write)

Description: the album (i.e. "ReLoad")

string Name() (read / write)

Description: the name of the track (i.e. "Unforgiven II")

number Filesize() (read / write)

Description: the filesize in bytes

number Duration() (read / write)

Description: the file duration in seconds

string Genre() (read / write)

Description: the genre (i.e. "Rock")

number Year() (read / write)

Description: the year (i.e. 1997)

string Comment() (read / write)

Description: the comment

number Bitrate() (read / write)

Description: the bitrate (i.e. 128 kbps)

number Tracknumber() (read / write)

Description: the track number (i.e. 4)

number Filedate() (read / write)

Description: the file's date (seconds past 1970)

string Custom1() (read / write)

Description: the MJ-specific "Custom1" field

string Custom2() (read / write)

Description: the MJ-specific "Custom2" field

string Custom3() (read / write)

Description: the MJ-specific "Custom3" field

number PlayCounter() (read / write)

Description: the number of times the track has been played in Media Center

number LastPlayed() (read / write)

Description: the date the file was last played in Media Center (seconds past 1970)

number Rating() (read / write)

Description: the rating (MJ-specific) (note: 0 = ?, otherwise 1-5)

string Filetype() (read / write)

Description: the extension of the file (used by MJ to choose playback plugins, etc.) (i.e. "mp3")

string Lyrics() (read / write)

Description: the lyrics

string Notes() (read / write)

Description: the notes

string AlbumArtist() (read / write)

Description: the album artist (auto) (to get the real field value of album artist use: Get("Album Artist", false))