Methods > Playlists > PlayListAddItemEx method

Remarks

Adds a song (item) to the loaded playlist.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

Public Function PlayListAddItemEx (

nPlayerIndex as Int16,

strPathname as string,

nIndex as Int16,

nItemType as enumPlayListItemType

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListAddItemEx (

Int16 nPlayerIndex,

string strPathname,

Int16 nIndex,

enumPlayListItemType nItemType

);

[C++]

public: enumErrorCodes PlayListAddItemEx (

Int16 nPlayerIndex,

string strPathname,

Int16 nIndex,

enumPlayListItemType nItemType

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that owns the playlist

strPathname

String containing the pathname of the element to add.

If the playlist has been loaded or created with volume automation enabled, you can add a new item containing all the needed mixing positions, volume automation points and cue points in one single shot by passing a well formatted XML string to this parameter; an example of well formatted string is the following:

<VolumePoint name="start fade-in" VolumeLevelLinear="0.0" PosSec="2.0" CurveType="5"

LeftX="11" LeftY="3" RightX="93" RightY="43" />

<VolumePoint name="start fade-out" VolumeLevelLinear="100.0" PosSec="11.9" CurveType="5"

LeftX="83" LeftY="13" RightX="32" RightY="41" />

</VolumePoints>

</CuePoints>

</Item>

For details about XML syntax of the string above refer to the How to manage Volume Automation tutorial.

If the playlist has been loaded or created without volume automation enabled, you can add a new encrypted item by passing a well formatted XML string to this parameter; an example of well formatted string is the following:

nIndex

Number representing the zero-based insertion position: if the nIndex parameter value exceed the playlist length, the song will be placed at the bottom of the playlist

nItemType

Type of item to add

Supported values are the following:

Mnemonic constant	Value	Meaning
PLAYLIST_ITEM_SOUND_FILE	0	Adds a single sound file whose pathname is found inside the strPathname parameter
PLAYLIST_ITEM_PLAYLIST_FILE	1	Adds full contents of an existing playlist file whose pathname is specified inside the strPathname parameter. This operation is performed inside a secondary thread so, when the method returns, the list of items could be still not completed. In this case the container application is informed about the loading advancement through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_PLAYLIST_LOAD_STARTED, EV_PLAYLIST_LOAD_PERC and EV_PLAYLIST_LOAD_DONE.
PLAYLIST_ITEM_DIRECTORY	2	Adds sound related contents of an existing directory whose path is specified inside the strPathname parameter. This operation is performed inside a secondary thread so, when the method returns, the list of items could be still not completed. In this case the container application is informed about the loading advancement through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_PLAYLIST_LOAD_STARTED, EV_PLAYLIST_LOAD_PERC and EV_PLAYLIST_LOAD_DONE.

Return value

Value	Meaning

Negative value	An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0)	The method call was successful.