home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Amiga Shareware Floppies / ma58.dms / ma58.adf / superplay-lib_DEV / Programmers / Docs / SPObject_Ref_ENG.doc < prev    next >
Encoding:
Text File  |  1996-05-27  |  19.8 KB  |  852 lines
  1.  
  2.    $VER: SPObject_Ref_ENG.doc V2.4 (21.10.95)
  3.  
  4.    © 1994-95 by Andreas R. Kleinert. All rights reserved.
  5.  
  6.    - Feel free to translate this Doc-File into other languages. -
  7.  
  8.           Andreas R. Kleinert,
  9.           Sandstrasse 1,
  10.           D-57072 Siegen,
  11.           Germany.
  12.  
  13.     EMail:  Fido             Andreas Kleinert 2:2457/435.10
  14.             Usenet/InterNet  Andreas_Kleinert@superview.ftn.sub.org
  15.  
  16.       If nothing else works, try one of these Fido-InterNet gateways:
  17.  
  18.             Andreas_Kleinert@p10.f435.n2457.z2.fido.sub.org (in Germany)
  19.             Andreas_Kleinert@p10.f435.n2457.z2.fidonet.org  (USA or other)
  20.  
  21.    * DO _NEVER_ ACCESS ANY SPOBJECTS DIRECTLY.
  22.    * DO NEVER BYPASS superplay.library !
  23.  
  24.    THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SPOBJECTS :
  25.  
  26.    Here is a listing of the function set, which any of the version 1
  27.    and version 2 SPObjects does contain, in an Autodoc-like style of
  28.    description :
  29.  
  30.         SPO_AllocHandle            ; since Version 1
  31.         SPO_FreeHandle
  32.         SPO_Read
  33.         SPO_StartReplay
  34.         SPO_Write
  35.         SPO_StopReplay
  36.         SPO_FreeResources
  37.         SPO_SetAccessMode
  38.         SPO_SetWriteSubType
  39.         SPO_SetWriteName
  40.         SPO_SetReadeName
  41.         SPO_FileInfoRequest
  42.         SVO_CheckFileType
  43.         SPO_SetReqIOWindow
  44.         SPO_ContinueReplay
  45.         SPO_FastForward
  46.         SPO_FastBackward
  47.         SPO_GetSampleBuffer         *** OBSOLETE : Use SPO_GetSampleList()
  48.         SPO_GetSampleInfo           *** OBSOLETE : Use SPO_GetSampleList()
  49.         SPO_GetSampleList          ; since Version 2
  50.         SPO_SetSampleList
  51.  
  52. -----------------------------------------------------------------------------
  53.    Functions available since Version 1 :
  54. -----------------------------------------------------------------------------
  55.  
  56.    NAME
  57.         SPO_AllocHandle
  58.  
  59.    SYNOPSIS
  60.  
  61.         APTR SPO_AllocHandle(APTR future)
  62.         D0   -$1e            A1
  63.  
  64.    FUNCTION
  65.  
  66.         Allocates a handle for accessing a Sample/Module via SPObjects.
  67.  
  68.    INPUT(S)
  69.  
  70.         future - always NULL yet
  71.  
  72.    RESULT
  73.  
  74.         A pointer to a new allocated Handle or NULL, if allocation failed.
  75.  
  76.    WARNING
  77.  
  78.         Test, if the result was NULL, or not !
  79.  
  80.    SINCE
  81.  
  82.         ... version 1 of the superplay.library.
  83.  
  84.    SEE ALSO
  85.  
  86.         SPO_FreeResources, SPO_FreeHandle
  87.  
  88. -----------------------------------------------------------------------------
  89.  
  90.    NAME
  91.         SPO_FreeHandle
  92.  
  93.    SYNOPSIS
  94.  
  95.         VOID SPO_FreeHandle(APTR handle)
  96.         D0   -$24           A1
  97.  
  98.    FUNCTION
  99.  
  100.        Stops playing, frees all Resources and delocates a Handle, which has
  101.        been allocated with SPO_AllocHandle before.
  102.  
  103.    INPUT(S)
  104.  
  105.         handle - a valid handle
  106.  
  107.    RESULT
  108.  
  109.         -
  110.  
  111.    SINCE
  112.  
  113.         ... version 1 of the superplay.library.
  114.  
  115.    SEE ALSO
  116.  
  117.         SPO_AllocHandle, SPO_StopReplay, SPO_FreeResources
  118.  
  119. -----------------------------------------------------------------------------
  120.  
  121.    NAME
  122.         SPO_Read
  123.  
  124.    SYNOPSIS
  125.  
  126.         ULONG SPO_Read(APTR handle)
  127.         D0    -$2a     A1
  128.  
  129.    FUNCTION
  130.  
  131.         Loads the Sample/Module described by FileName, which then may
  132.         e.g. be replayed by SPO_StartReplay.
  133.  
  134.    INPUT(S)
  135.  
  136.         handle   - a valid handle
  137.  
  138.    RESULT
  139.  
  140.         NULL or an adequate SPERR-Errorcode.
  141.  
  142.    SINCE
  143.  
  144.         ... version 1 of the superplay.library.
  145.  
  146.    SEE ALSO
  147.  
  148.         SPO_AllocHandle, SPO_StopReplay, SPO_StartReplay, SPO_ContinueReplay,
  149.         SPO_FastForward, SPO_FastBackward, SPO_FreeHandle
  150.  
  151. -----------------------------------------------------------------------------
  152.  
  153.    NAME
  154.         SPO_StartReplay
  155.  
  156.    SYNOPSIS
  157.  
  158.         ULONG SPO_StartReplay(APTR handle)
  159.         D0    -$30            A1
  160.  
  161.    FUNCTION
  162.  
  163.         Play the Sample/Module described by FileName, which has been loaded
  164.         via SPO_Read before.
  165.  
  166.         Playing can be stopped either via full delocation of the handle
  167.         or temporal interruption with SPO_StopReplay.
  168.  
  169.    INPUT(S)
  170.  
  171.         handle   - a valid handle
  172.  
  173.    RESULT
  174.  
  175.         NULL or an adequate SPERR-Errorcode.
  176.  
  177.    SINCE
  178.  
  179.         ... version 1 of the superplay.library.
  180.  
  181.    SEE ALSO
  182.  
  183.         SPO_AllocHandle, SPO_Read, SPO_StopReplay, SPO_ContinueReplay,
  184.         SPO_FastForward, SPO_FastBackward, SPO_FreeHandle
  185.  
  186. -----------------------------------------------------------------------------
  187.  
  188.    NAME
  189.         SPO_Write
  190.  
  191.    SYNOPSIS
  192.  
  193.         ULONG SPO_Write(APTR handle, struct SPObjectBase *SourceBase,
  194.         D0    -$36      A1           A2
  195.  
  196.                         APTR source_handle)
  197.                         A3
  198.  
  199.    FUNCTION
  200.  
  201.         This functions allows to access an other SPObject, get the Sample-
  202.         Data from there (only works with SampleType-SPObjects) and
  203.         then writes this data in its own FileFormat.
  204.  
  205.         *** NEW FEATURE : ***
  206.  
  207.         This functions acts different in Versions >= 2 :
  208.  
  209.         1) If "SourceBase" and "source_handle" are both NULL,
  210.            it is checked, whether a SampleList has been set via
  211.            "SPO_SetSampleList()", and then this SampleList is completely
  212.            saved.
  213.  
  214.            ELSE
  215.  
  216.         2) a) If a Version 1 SPObject is the Source, the old behaviour
  217.               takes place.
  218.            b) If a Version 2 SPObject takes place, the new SampleList
  219.               functions are supported (and completely saved).
  220.  
  221.         So, what's new ? Well, if you've any self-created SampleLists,
  222.         you now can save them by just setting them via SPO_SetSampleList()
  223.         and then calling SPO_Write() with NULL parameters for the
  224.         Source-SPObject variables.
  225.  
  226.    INPUT(S)
  227.  
  228.         handle        - a valid handle
  229.                         (used for Write Access)
  230.         SourceBase    - pointer to Base of other SPObject
  231.                         (may be NULL for V2+ SPObjects)
  232.         source_handle - handle for accessing the other SPObject
  233.                         (may be NULL for V2+ SPObjects)
  234.  
  235.    RESULT
  236.  
  237.         NULL or an adequate SPERR-Errorcode.
  238.  
  239.    SINCE
  240.  
  241.         ... version 1 of the superplay.library.
  242.  
  243.    SEE ALSO
  244.  
  245.         SPO_AllocHandle, SPO_Read, SPO_FreeHandle
  246.  
  247. -----------------------------------------------------------------------------
  248.  
  249.    NAME
  250.         SPO_StopReplay
  251.  
  252.    SYNOPSIS
  253.  
  254.         VOID SPO_StopReplay(APTR handle)
  255.         D0   -$3c           A1
  256.  
  257.    FUNCTION
  258.  
  259.         Stops playing the Sample/Module, indentified by the handle.
  260.         Some SPObjects support to continue the Sample/Module with
  261.         SPO_ContinueReplay after calling SPO_StopReplay.
  262.  
  263.    INPUT(S)
  264.  
  265.         handle - a valid handle
  266.  
  267.    RESULT
  268.  
  269.         -
  270.  
  271.    SINCE
  272.  
  273.         ... version 1 of the superplay.library.
  274.  
  275.    SEE ALSO
  276.  
  277.         SPO_ContinueReplay, SPO_FreeResources, SPO_FreeHandle
  278.  
  279. -----------------------------------------------------------------------------
  280.  
  281.    NAME
  282.         SPO_FreeResources
  283.  
  284.    SYNOPSIS
  285.  
  286.         VOID SPO_FreeResources(APTR handle)
  287.         D0   -$42              A1
  288.  
  289.    FUNCTION
  290.  
  291.         Frees all resources belonging to the specific Sample/Module,
  292.         indentified by the handle, which are not needed to just replay it.
  293.         Playing of the Sample/Module is not stopped and/or interrupted.
  294.  
  295.    INPUT(S)
  296.  
  297.         handle - a valid handle
  298.  
  299.    RESULT
  300.  
  301.         -
  302.  
  303.    SINCE
  304.  
  305.         ... version 1 of the superplay.library.
  306.  
  307.    SEE ALSO
  308.  
  309.         SPO_AllocHandle, SPO_StopReplay, SPO_FreeHandle
  310.  
  311. -----------------------------------------------------------------------------
  312.  
  313.    NAME
  314.         SPO_SetAccessMode
  315.  
  316.    SYNOPSIS
  317.  
  318.         ULONG SPO_SetAccessMode(APTR handle, ULONG mode)
  319.         D0    -$48              A1           D1
  320.  
  321.    FUNCTION
  322.  
  323.         Initializes a Handle for ClipBoard or AmigaDOS access,
  324.         depending on the "mode" parameter.
  325.  
  326.    INPUT(S)
  327.  
  328.         handle - a valid handle
  329.         mode   - access mode value
  330.  
  331.  
  332.    RESULT
  333.  
  334.         NULL or an adequate SPERR-Errorcode.
  335.  
  336.    SINCE
  337.  
  338.         ... version 1 of the superplay.library.
  339.  
  340.    SEE ALSO
  341.  
  342.         -
  343.  
  344. -----------------------------------------------------------------------------
  345.  
  346.    NAME
  347.         SPO_SetWriteSubType
  348.  
  349.    SYNOPSIS
  350.  
  351.         ULONG SPO_SetWriteSubType(APTR handle, ULONG write_type, APTR future)
  352.         D0    -$4e                A1           A2                A3
  353.  
  354.    FUNCTION
  355.  
  356.         Sets the write_type for a SPO_Write() call.
  357.         See description there and example SourceCodes for more and
  358.         detailed information.
  359.  
  360.    INPUT(S)
  361.  
  362.         handle     - a valid handle
  363.         write_type - a valid temporary write_type code form the SPObject List
  364.         future     - always NULL yet
  365.  
  366.  
  367.    RESULT
  368.  
  369.         NULL or an adequate SPERR-Errorcode.
  370.  
  371.    SINCE
  372.  
  373.         ... version 1 of the superplay.library.
  374.  
  375.    SEE ALSO
  376.  
  377.         SPO_Write
  378.  
  379. -----------------------------------------------------------------------------
  380.  
  381.    NAME
  382.         SPO_SetWriteName
  383.  
  384.    SYNOPSIS
  385.  
  386.         ULONG SPO_SetWriteName(APTR handle, ULONG write_name, APTR future)
  387.         D0    -$54             A1           A2                A3
  388.  
  389.    FUNCTION
  390.  
  391.         Sets the write_name for a SPO_Write() call.
  392.         See description there and example SourceCodes for more and
  393.         detailed information.
  394.  
  395.    INPUT(S)
  396.  
  397.         handle     - a valid handle
  398.         write_name - a valid AmigaDOS FilePath and -Name description
  399.         future     - always NULL yet
  400.  
  401.  
  402.    RESULT
  403.  
  404.         NULL or an adequate SPERR-Errorcode.
  405.  
  406.    SINCE
  407.  
  408.         ... version 1 of the superplay.library.
  409.  
  410.    SEE ALSO
  411.  
  412.         SPO_Write
  413.  
  414. -----------------------------------------------------------------------------
  415.  
  416.    NAME
  417.         SPO_SetReadName
  418.  
  419.    SYNOPSIS
  420.  
  421.         ULONG SPO_SetReadName(APTR handle, ULONG reade_name, APTR future)
  422.         D0    -$5a            A1           A2                A3
  423.  
  424.    FUNCTION
  425.  
  426.         Sets the reade_name for a SPO_Read() call.
  427.         See description there and example SourceCodes for more and
  428.         detailed information.
  429.  
  430.    INPUT(S)
  431.  
  432.         handle     - a valid handle
  433.         write_name - a valid AmigaDOS FilePath and -Name description
  434.         future     - always NULL yet
  435.  
  436.  
  437.    RESULT
  438.  
  439.         NULL or an adequate SPERR-Errorcode.
  440.  
  441.    SINCE
  442.  
  443.         ... version 1 of the superplay.library.
  444.  
  445.    SEE ALSO
  446.  
  447.         SPO_Write
  448.  
  449. -----------------------------------------------------------------------------
  450.  
  451.    NAME
  452.         SPO_FileInfoRequest
  453.  
  454.    SYNOPSIS
  455.  
  456.         ULONG SPO_FileInfoRequest(APTR handle, struct Window *window,
  457.         D0    -$60                A1           A2
  458.  
  459.                                   APTR future)
  460.                                   A3
  461.  
  462.    FUNCTION
  463.  
  464.         Pops up an Info-Requester with more or less detailed information
  465.         on the currently loaded Sample/Module.
  466.         A window pointer may be given to select the place to pop it up.
  467.  
  468.    INPUT(S)
  469.  
  470.         handle - a valid handle
  471.         window - a valid Window Pointer or NULL
  472.         future - always NULL yet
  473.  
  474.  
  475.    RESULT
  476.  
  477.         NULL or an adequate SPERR-Errorcode.
  478.  
  479.    SINCE
  480.  
  481.         ... version 1 of the superplay.library.
  482.  
  483.    SEE ALSO
  484.  
  485.         SPO_SetReqIOWindow
  486.  
  487. -----------------------------------------------------------------------------
  488.  
  489.    NAME
  490.         SPO_CheckFileType
  491.  
  492.    SYNOPSIS
  493.  
  494.         ULONG SPO_CheckFileType(BPTR filehandle, UBYTE *filename,
  495.         D0    -$66              A1                 A2
  496.  
  497.                                 struct SPOCheckFile *spo_check)
  498.                                 A3
  499.  
  500.    FUNCTION
  501.  
  502.         Checks, if the given file (or ClipBoard entry, or whatever)
  503.         fits to this SPObject and can be handled therein.
  504.  
  505.         Upto Version 2 of superplay.library ClipBoard-Support with
  506.         external SPObjects would not have worked at all.
  507.         Since V2 the specification of external Version 2 SPObjects
  508.         has been modified to allow ClipBoard and other media usage :
  509.         To preserve compatibility, this has been done by using the
  510.         "future" parameter as a pointer to a structure (defined in
  511.         "include:spobjects/spobjects.h"), which contains media
  512.         information.
  513.  
  514.         This pointer may be NULL, so that you have to assume default
  515.         settings, if there's not such a structure.
  516.         For disk-access, this pointer will not be set at all, anyway.
  517.  
  518.         Also be prepared, to handle NULL pointers to filename :
  519.         if ClipBoard usage is forced, there will no filename be needed.
  520.         If you don't support any filename-less medias, just do a silent
  521.         exit.
  522.         Currently - for compatibility reasons - superplay.library will
  523.         supply a dummy filename and a dummy file for those SPObjects,
  524.         which may not handle a NULL pointer correctly.
  525.  
  526.         So handle SPOCheckFile structures with a HIGHER priority, because
  527.         currently there's always a dummy-file (mostly empty) available.
  528.  
  529.    INPUT(S)
  530.  
  531.         handle    - a valid handle
  532.         name      - a valid AmigaDOS FileName
  533.         spo_check - a pointer to a SPOCheckFile structure or NULL
  534.                     for disk-access (default)
  535.  
  536.    RESULT
  537.  
  538.         NULL or an adequate SVERR-Errorcode.
  539.  
  540.    SINCE
  541.  
  542.         ... Version 1 SPObjects.
  543.  
  544.    SEE ALSO
  545.  
  546.         -
  547.  
  548. -----------------------------------------------------------------------------
  549.  
  550.    NAME
  551.         SPO_SetReqIOWindow
  552.  
  553.    SYNOPSIS
  554.  
  555.         ULONG SPO_SetReqIOWindow(APTR handle, struct Window *window)
  556.         D0    -$6c               A1           A2
  557.  
  558.    FUNCTION
  559.  
  560.         Sets a new Default-Window (default : IntuitionBase->FirstWindow)
  561.         for any Requester IO.
  562.  
  563.    INPUT(S)
  564.  
  565.         handle - a valid handle
  566.         window - a valid Window Pointer or NULL
  567.  
  568.    RESULT
  569.  
  570.         NULL or an adequate SPERR-Errorcode.
  571.  
  572.    SINCE
  573.  
  574.         ... version 1 of the superplay.library.
  575.  
  576.    SEE ALSO
  577.  
  578.         SPO_FileInfoReq
  579.  
  580. -----------------------------------------------------------------------------
  581.  
  582.    NAME
  583.         SPO_ContinueReplay
  584.  
  585.    SYNOPSIS
  586.  
  587.         ULONG SPO_ContinueReplay(APTR handle)
  588.         D0    -$72               A1
  589.  
  590.    FUNCTION
  591.  
  592.         Some SPObjects support to continue a Sample/Module which
  593.         has been stopped by calling SPO_StopReplay.
  594.  
  595.    INPUT(S)
  596.  
  597.         handle - a valid handle
  598.  
  599.    RESULT
  600.  
  601.         NULL or an adequate SPERR-Errorcode.
  602.  
  603.    SINCE
  604.  
  605.         ... version 1 of the superplay.library.
  606.  
  607.    SEE ALSO
  608.  
  609.         SPO_SuperPlay, SPO_StopReplay
  610.  
  611. -----------------------------------------------------------------------------
  612.  
  613.    NAME
  614.         SPO_FastForward
  615.  
  616.    SYNOPSIS
  617.  
  618.         ULONG SPO_FastForward(APTR handle)
  619.         D0    -$78            A1
  620.  
  621.    FUNCTION
  622.  
  623.         Some SPObjects might support a "cassette recorder"-like way
  624.         to browse trough a Sample/Module via FastForward and Rewind.
  625.  
  626.    INPUT(S)
  627.  
  628.         handle - a valid handle
  629.  
  630.    RESULT
  631.  
  632.         NULL or an adequate SPERR-Errorcode.
  633.  
  634.    SINCE
  635.  
  636.         ... version 1 of the superplay.library.
  637.  
  638.    SEE ALSO
  639.  
  640.         SPO_FastBackward
  641.  
  642. -----------------------------------------------------------------------------
  643.  
  644.    NAME
  645.         SPO_FastBackward
  646.  
  647.    SYNOPSIS
  648.  
  649.         ULONG SPO_FastBackward(APTR handle)
  650.         D0    -$7e            A1
  651.  
  652.    FUNCTION
  653.  
  654.         Some SPObjects might support a "cassette recorder"-like way
  655.         to browse trough a Sample/Module via FastForward and Rewind.
  656.  
  657.    INPUT(S)
  658.  
  659.         handle - a valid handle
  660.  
  661.    RESULT
  662.  
  663.         NULL or an adequate SPERR-Errorcode.
  664.  
  665.    SINCE
  666.  
  667.         ... version 1 of the superplay.library.
  668.  
  669.    SEE ALSO
  670.  
  671.         SPO_FastForward
  672.  
  673. -----------------------------------------------------------------------------
  674.  
  675.    NAME
  676.         SPO_GetSampleBuffer         *** OBSOLETE : Use SPO_GetSampleList()
  677.  
  678.    SYNOPSIS
  679.  
  680.         ULONG SPO_GetSampleBuffer(APTR handle, UBYTE **buffer,
  681.         D0    -$84                A1           A2
  682.  
  683.                                   ULONG *buffersize)
  684.                                   A3
  685.  
  686.    FUNCTION
  687.  
  688.         With Version 1 SPObjects, this is the only possibility to get
  689.         a pointer to SampleBuffers.
  690.  
  691.         This function only works with SampleType-SPObjects and is used
  692.         always, when Samples are converted from from FileFormat into
  693.         an other.
  694.  
  695.         This function should not be used for any other purposes, since it
  696.         is OBSOLETE since Version 2 of the SPObject specification.
  697.         There's no direct pass-through from this function to superplay.library,
  698.         but it would not suffice, anyway, since some FileFormats may
  699.         contain MORE THAN ONE Sample.
  700.  
  701.         Use SPO_GetSampleList instead, which can handle more than one
  702.         Sample and also returns the information related to them.
  703.  
  704.    INPUT(S)
  705.  
  706.         handle     - a valid handle
  707.         buffer     - a pointer to a buffer pointer
  708.         buffersize - a pointer to a buffersize pointer
  709.  
  710.    RESULT
  711.  
  712.         NULL or an adequate SPERR-Errorcode.
  713.  
  714.    SINCE
  715.  
  716.         ... version 1 of the superplay.library.
  717.  
  718.    SEE ALSO
  719.  
  720.         SPO_GetSampleList
  721.  
  722. -----------------------------------------------------------------------------
  723.  
  724.    NAME
  725.         SPO_GetSampleInfo           *** OBSOLETE : Use SPO_GetSampleList()
  726.  
  727.    SYNOPSIS
  728.  
  729.         ULONG SPO_GetSampleBuffer(APTR handle, ULONG *samplesPerSec,
  730.         D0    -$8a                A1           A2
  731.  
  732.                                   ULONG *volume, APTR future)
  733.                                   A3             D1
  734.  
  735.    FUNCTION
  736.  
  737.         With Version 1 SPObjects, this is the only possibility to get
  738.         a pointer to Sample information.
  739.  
  740.         This function only works with SampleType-SPObjects and is used
  741.         always, when Samples are converted from from FileFormat into
  742.         an other.
  743.  
  744.         This function should not be used for any other purposes, since it
  745.         is OBSOLETE since Version 2 of the SPObject specification.
  746.         There's no direct pass-through from this function to superplay.library,
  747.         but it would not suffice, anyway, since some FileFormats may
  748.         contain MORE THAN ONE Sample.
  749.  
  750.         Use SPO_GetSampleList instead, which can handle more than one
  751.         Sample and also returns the information related to them.
  752.  
  753.         This function only returns info on 8 Bit Samples.
  754.  
  755.    INPUT(S)
  756.  
  757.         handle        - a valid handle
  758.         samplesPerSec - a pointer to a buffer pointer
  759.         volume        - a pointer to a buffersize pointer
  760.         future        - always NULL yet
  761.  
  762.    RESULT
  763.  
  764.         NULL or an adequate SPERR-Errorcode.
  765.  
  766.    SINCE
  767.  
  768.         ... version 1 of the superplay.library.
  769.  
  770.    SEE ALSO
  771.  
  772.         SPO_GetSampleList
  773.  
  774. -----------------------------------------------------------------------------
  775.    Functions added with Version 2 :
  776. -----------------------------------------------------------------------------
  777.  
  778.    NAME
  779.         SPO_GetSampleList
  780.  
  781.    SYNOPSIS
  782.  
  783.         ULONG SPO_GetSampleList(APTR handle, struct SPO_SampleList **list)
  784.         D0    -$90              A1           A2
  785.  
  786.    FUNCTION
  787.  
  788.         While/after loading a Sample-File Version 2 SPObjects might create
  789.         a special list of all Samples, which appear in the File.
  790.         This will usually be one one Sample for SampleFiles, but many more
  791.         for ModuleFiles.
  792.  
  793.         Not all SPObjects, especially not all ModuleType-SPObjects,
  794.         may support this and will return an error value or an empty list.
  795.  
  796.    INPUT(S)
  797.  
  798.         handle - a valid handle
  799.         list   - a pointer to a SPO_SampleList pointer
  800.  
  801.    RESULT
  802.  
  803.         NULL or an adequate SPERR-Errorcode.
  804.  
  805.    SINCE
  806.  
  807.         ... version 2 of the superplay.library.
  808.  
  809.    SEE ALSO
  810.  
  811.         SPO_SetSampleList
  812.  
  813. -----------------------------------------------------------------------------
  814.  
  815.    NAME
  816.         SPO_SetSampleList
  817.  
  818.    SYNOPSIS
  819.  
  820.         ULONG SPO_SetSampleList(APTR handle, struct SPO_SampleList *list)
  821.         D0    -$96              A1           A2
  822.  
  823.    FUNCTION
  824.  
  825.         For saving Sample-Files with Version 2 SPObjects, there may be used
  826.         a special list of all Samples, which should appear in the File.
  827.  
  828.         This will usually be one one Sample for SampleFiles, but many more
  829.         for ModuleFiles.
  830.  
  831.         Not all SPObjects, especially not all ModuleType-SPObjects,
  832.         may support this and will return SPERR_ACTION_NOT_SUPPORTED.
  833.  
  834.    INPUT(S)
  835.  
  836.         handle - a valid handle
  837.         list   - a pointer to a SPO_SampleList
  838.  
  839.    RESULT
  840.  
  841.         NULL or an adequate SPERR-Errorcode.
  842.  
  843.    SINCE
  844.  
  845.         ... version 2 of the superplay.library.
  846.  
  847.    SEE ALSO
  848.  
  849.         SPO_GetSampleList
  850.  
  851. -----------------------------------------------------------------------------
  852.