6
ORDAudio Reference Information

Oracle interMedia contains information about the ORDAudio type:

• Object type -- see Section 6.1.
• Constructors -- see Section 6.2.
• Methods -- see Section 6.3.
• Packages or PL/SQL plug-ins -- see Section 6.4.

The examples in this chapter assume that the test audio table TAUD has been created and filled with data. This table was created using the SQL statements described in Section 6.3.1.

Methods invoked at the ORDSource level that are handed off to the source plug-in for processing have ctx(RAW(4000)) as the first argument. Before calling any of these methods for the first time, the client must allocate the ctx structure, initialize it to NULL, and invoke the openSource( ) method. At this point, the source plug-in can initialize context for this client. When processing is complete, the client should invoke the closeSource( ) method.

Methods invoked from a source plug-in call have the first argument as ctx (RAW(4000)).

Methods invoked at the ORDAudio level that are handed off to the format plug-in for processing have ctx (RAW(4000)) as the first argument. Before calling any of these methods for the first time, the client must allocate the ctx structure and initialize it to NULL.

You should use any of the individual set methods to set the value of the attribute for an object for formats not natively supported; otherwise, for formats natively supported, use the setProperties( ) method to populate the attributes of the object.

6.1 Object Types

Oracle interMedia describes the ORDAudio object type, which supports the storage and management of audio data.

---

ORDAudio Object Type

The ORDAudio object type supports the storage and management of audio data. This object type is defined as follows:

CREATE OR REPLACE TYPE ORDAudio
AS OBJECT
(
  -- ATTRIBUTES 
description         VARCHAR2(4000),
source              ORDSource,
format              VARCHAR2(31),
mimeType            VARCHAR2(4000),
comments            CLOB, 
  -- AUDIO RELATED ATTRIBUTES 
encoding            VARCHAR2(256),
numberOfChannels    INTEGER,
samplingRate        INTEGER,
sampleSize          INTEGER,
compressionType     VARCHAR2(4000),
audioDuration       INTEGER,

  -- METHODS 
-- CONSTRUCTORS
--
STATIC FUNCTION init( ) RETURN ORDAudio,
STATIC FUNCTION init(srcType     IN VARCHAR2,
                     srcLocation IN VARCHAR2,
                     srcName     IN VARCHAR2) RETURN ORDAudio,
-- Methods associated with the date attribute
MEMBER FUNCTION getUpdateTime( ) RETURN DATE,
PRAGMA RESTRICT_REFERENCES(getUpdateTime, WNDS, WNPS, RNDS, RNPS),
MEMBER PROCEDURE setUpdateTime(current_time DATE),
-- Methods associated with the description attribute
MEMBER PROCEDURE setDescription(user_description IN VARCHAR2),
MEMBER FUNCTION getDescription( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getDescription, WNDS, WNPS, RNDS, RNPS),

-- Methods associated with the mimeType attribute
MEMBER PROCEDURE setMimeType(mime IN VARCHAR2),
MEMBER FUNCTION getMimeType( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getMimeType, WNDS, WNPS, RNDS, RNPS),

-- Methods associated with the source attribute
MEMBER FUNCTION processSourceCommand(
                                     ctx       IN OUT RAW,
                                     cmd       IN VARCHAR2,
                                     arguments IN VARCHAR2,
                                     result    OUT RAW)
                RETURN RAW,

MEMBER FUNCTION  isLocal( ) RETURN BOOLEAN,
PRAGMA RESTRICT_REFERENCES(isLocal, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE  setLocal( ),
MEMBER PROCEDURE  clearLocal( ),

MEMBER PROCEDURE setSource(
                           source_type     IN VARCHAR2,
                           source_location IN VARCHAR2,
                           source_name     IN VARCHAR2),
MEMBER FUNCTION getSource( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSource, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION getSourceType( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSourceType, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION getSourceLocation( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSourceLocation, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION getSourceName( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSourceName, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE import(ctx IN OUT RAW),
MEMBER PROCEDURE importFrom(
                            ctx             IN OUT RAW,
                            source_type     IN VARCHAR2,
                            source_location IN VARCHAR2, 
                            source_name     IN VARCHAR2),
MEMBER PROCEDURE export(
                        ctx             IN OUT RAW,
                        source_type     IN VARCHAR2,
                        source_location IN VARCHAR2,
                        source_name     IN VARCHAR2),
MEMBER FUNCTION getContentLength(ctx IN OUT RAW) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE getContentInLob(
                                ctx      IN OUT RAW,
                                dest_lob IN OUT NOCOPY BLOB,
                                mimeType OUT VARCHAR2,
                                format   OUT VARCHAR2),

MEMBER FUNCTION getContent( ) RETURN BLOB,
PRAGMA RESTRICT_REFERENCES(getContent, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE deleteContent( ),

MEMBER FUNCTION getBFILE( ) RETURN BFILE,
PRAGMA RESTRICT_REFERENCES(getBFILE, WNDS, WNPS, RNDS, RNPS),

-- Methods associated with file operations on the source
MEMBER FUNCTION openSource(userArg IN RAW, ctx OUT RAW) RETURN INTEGER,
MEMBER FUNCTION closeSource(ctx IN OUT RAW) RETURN INTEGER,
MEMBER FUNCTION trimSource(ctx     IN OUT RAW,
                           newlen  IN INTEGER) RETURN INTEGER,
MEMBER PROCEDURE readFromSource(
                                ctx      IN OUT RAW,
                                startPos IN INTEGER,
                                numBytes IN OUT INTEGER,
                                buffer   OUT RAW), 
MEMBER PROCEDURE writeToSource(
                               ctx      IN OUT RAW,
                               startPos IN INTEGER,
                               numBytes IN OUT INTEGER,
                               buffer   IN RAW), 

-- Methods associated with audio attributes accessors
MEMBER PROCEDURE setFormat(knownformat IN VARCHAR2),
MEMBER FUNCTION getFormat( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getFormat, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE setEncoding(knownEncoding IN VARCHAR2),
MEMBER FUNCTION getEncoding( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getEncoding, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE setNumberOfChannels(knownNumberOfChannels IN INTEGER),
MEMBER FUNCTION getNumberOfChannels( ) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getNumberOfChannels, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE setSamplingRate(knownSamplingRate IN INTEGER),
MEMBER FUNCTION getSamplingRate( ) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getSamplingRate, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE setSampleSize(knownSampleSize IN INTEGER),
MEMBER FUNCTION getSampleSize( ) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getSampleSize, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE setCompressionType(knownCompressionType IN VARCHAR2),
MEMBER FUNCTION getCompressionType( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getCompressionType, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE setAudioDuration(knownAudioDuration IN INTEGER),
MEMBER FUNCTION getAudioDuration( ) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getAudioDuration, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE setKnownAttributes(
                                    knownFormat IN VARCHAR2,
                                    knownEncoding IN VARCHAR2,
                                    knownNumberOfChannels IN INTEGER,
                                    knownSamplingRate IN INTEGER,
                                    knownSampleSize IN INTEGER,
                                    knownCompressionType IN VARCHAR2,
                                    knownAudioDuration IN INTEGER),

-- Methods associated with setting all the properties
MEMBER PROCEDURE setProperties(ctx         IN OUT RAW,
                               setComments IN BOOLEAN),
MEMBER FUNCTION checkProperties(ctx IN OUT RAW) RETURN BOOLEAN,

MEMBER FUNCTION getAttribute(
                             ctx  IN OUT RAW,
                             name IN VARCHAR2) RETURN VARCHAR2,

MEMBER PROCEDURE getAllAttributes(
                                  ctx        IN OUT RAW, 
                                  attributes IN OUT NOCOPY CLOB), 

-- Methods associated with audio processing
MEMBER FUNCTION processAudioCommand(
                                    ctx       IN OUT RAW, 
                                    cmd       IN VARCHAR2, 
                                    arguments IN VARCHAR2, 
                                    result    OUT RAW)
                RETURN RAW
);

where:

6.2 Constructors

This section describes the constructor functions.

The interMedia constructor functions are as follows:

• init( )
• init(srcType,srcLocation,srcName)

---

init( )

Format

init( ) RETURN ORDAudio;

Description

Allows for easy initialization of instances of the ORDAudio object type.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

This static method initializes all the ORDAudio attributes to NULL with the following exceptions:

• source.updateTime is set to SYSDATE
• source.local is set to 1 (local)
• source.localData is set to empty_blob

You should begin using the init( ) method as soon as possible to allow you to more easily initialize the ORDAudio object type, especially if the ORDAudio type evolves and attributes are added in a future release. INSERT statements left unchanged using the default constructor (which initializes each object attribute), will fail under these circumstances.

Examples

Initialize the ORDAudio object attributes:

BEGIN
INSERT INTO taud VALUES (ORDSYS.ORDAudio.init());
END;
/

---

init(srcType,srcLocation,srcName)

Format

init(srcType IN VARCHAR2,

srcLocation IN VARCHAR2,

srcName IN VARCHAR2)

RETURN ORDAudio;

Description

Allows for easy initialization of instances of the ORDAudio object type.

Parameters

srcType

The source type of the audio data.

srcLocation

The source location of the audio data.

srcName

The source name of the audio data.

Pragmas

None.

Exceptions

None.

Usage Notes

This static method initializes all the ORDAudio attributes to NULL with the following exceptions:

• source.updateTime is set to SYSDATE
• source.local is set to 0
• source.localData is set to empty_blob
• source.srcType is set to the input value
• source.srcLocation is set to the input value
• source.srcName is set to the input value

You should begin using the init( ) method as soon as possible to allow you to more easily initialize the ORDAudio object type, especially if the ORDAudio type evolves and attributes are added in a future release. INSERT statements left unchanged using the default constructor (which initializes each object attribute), will fail under these circumstances.

Examples

Initialize the ORDAudio object attributes:

BEGIN
INSERT INTO taud VALUES (ORDSYS.ORDAudio.init('file','AUDDIR','audio1.au'));
END;
/

6.3 Methods

This section presents reference information on the Oracle interMedia methods used for audio data manipulation. These methods are described in the following groupings:

ORDAudio Methods Associated with the updateTime Attribute

• getUpdateTime( ): returns the time when the audio object was last updated. See "getUpdateTime( )" for information.
• setUpdateTime( ): sets the update time for the audio object. This method is called implicitly by methods that modify natively supported audio formats. See "setUpdateTime( )" for information.

ORDAudio Methods Associated with the description Attribute

• setDescription( ): sets the description of the audio data. See "setDescription( )".
• getDescription( ): returns the description of the audio data. See "getDescription( )".

ORDAudio Methods Associated with mimeType Attribute

• setMimeType( ): sets the MIME type of the stored audio data. This method is called implicitly by any method that modifies natively supported audio formats. See "setMimeType( )" for information.
• getMimeType( ): returns the MIME type of the stored audio data. See "getMimeType( )" for information.

ORDAudio Methods Associated with the source Attribute

• processSourceCommand( ): sends a command and related arguments to the source plug-in. See "processSourceCommand( )" for information.
• isLocal( ): returns TRUE if the data is stored locally in a BLOB or FALSE if the data is external. See "isLocal( )" for information.
• setLocal( ): sets a flag to indicate that the data is stored locally in a BLOB. See "setLocal( )" for information.
• clearLocal( ): clears the flag to indicate that the data is stored externally. See "clearLocal( )" for information.
• setSource( ): sets the source information to where audio data is found. See "setSource( )" for information.
• getSource( ): returns a formatted string containing complete information about the external data source formatted as a URL. See "getSource( )" for information.
• getSourceType( ): returns the external source type of the audio data. See "getSourceType( )" for information.
• getSourceLocation( ): returns the external source location of the audio data. See "getSourceLocation( )" for information.
• getSourceName( ): returns the external source name of the audio data. See "getSourceName( )" for information.
• import( ): transfers data from an external data source (specified by calling setSourceInformation( )) to the local source (localData) within an Oracle database, setting the value of the local attribute to "1", meaning local and updating the timestamp. See "import( )".
• importFrom( ): transfers data from the specified external data source (source type, location, name) to the local source (localData) within an Oracle database, setting the value of the local attribute to "1", meaning local and updating the timestamp. See "importFrom( )".
• export( ): copies data from a local source (localData) within an Oracle database to the specified external data source, and stores source information in the source. See "export( )" for information.

  Note: The export( ) method natively supports only sources of source type file. User-defined sources may support the export( ) method.

• getContentLength( ): returns the length of the data source (as number of bytes). See "getContentLength( )".
• getContentInLob( ): returns content into a temporary LOB. See "getContentInLob( )" for information.
• getContent( ): returns the handle to the BLOB used to store contents locally. See "getContent( )" for information.
• deleteContent( ): deletes the content of the local BLOB. See "deleteContent( )" for information.
• getBFILE( ): returns the external content as a BFILE. See "getBFILE( )" for information.

ORDAudio Methods Associated with File Operations

• openSource( ): opens a data source or a BLOB. See "openSource( )" for information.
• closeSource( ): closes a data source or a BLOB. See "closeSource( )" for information.
• trimSource( ): trims a data source or a BLOB. See "trimSource( )" for information.
• readFromSource( ): reads a buffer of n bytes from a source beginning at a start position. See "readFromSource( )" for information.
• writeToSource( ): writes a buffer of n bytes to a source beginning at a start position. See "writeToSource( )" for information.

ORDAudio Methods Associated with Audio Attributes Accessors

• setFormat( ): sets the object attribute value of the format of the audio data. See "setFormat( )" for information.
• getFormat( ): returns the object attribute value of the format in which the audio data is stored. See "getFormat( )".
• setEncoding( ): sets the object attribute value of the encoding type of the audio data. See "setEncoding( )".
• getEncoding( ): returns the object attribute value of the encoding type of the audio data. See "getEncoding( )".
• setNumberOfChannels( ): sets the object attribute value of the number of audio channels of the audio data. See "setNumberOfChannels( )".
• getNumberOfChannels( ): returns the object attribute value of the number of audio channels in the audio data. See "getNumberOfChannels( )".
• setSamplingRate( ): sets the object attribute value of the sampling rate of the audio data. See "setSamplingRate( )".
• getSamplingRate( ): returns the object attribute value of the sampling rate in samples per second at which the audio data was recorded. See "getSamplingRate( )".
• setSampleSize( ): sets the object attribute value of the sample width or number of samples of audio in the data. See "setSampleSize( )".
• getSampleSize( ): returns the object attribute value of the sample width or number of samples of audio in the data. See "getSampleSize( )".
• setCompressionType( ): sets the object attribute value of the compression type of the audio data. See "setCompressionType( )".
• getCompressionType( ): returns the object attribute value of the compression type of the audio data. See "getCompressionType( )".
• setAudioDuration( ): sets the object attribute value of the total time value for the time required to play the audio data. See "setAudioDuration( )".
• getAudioDuration( ): returns the object attribute value of the total time required to play the audio data. See "getAudioDuration( )".
• setKnownAttributes( ): sets known audio attributes including format, encoding type, number of channels, sampling rate, sample size, compression type, and audio duration of the audio data. The parameters are passed in with this call. See "setKnownAttributes( )".
• setProperties( ): reads the audio data to get the values of the object attributes and then stores them in the object. If the value for the setComments parameter is TRUE, then the comments field of the object will be populated with a rich set of format and application properties of the audio object in XML form, identical to what is provided by the interMedia Annotator utility. See "setProperties( )".

  For the known attributes that ORDAudio understands, it sets the properties for these attributes. These include: format, encoding type, data type, number of channels, sampling rate, and sample size of the audio data. See "setMimeType( )" for information.

• checkProperties( ): calls the format plug-in to check the properties including format, encoding type, number of channels, sampling rate, and sample size of the audio data, and returns a Boolean value TRUE if the properties stored in object attributes match those in the audio data. See "checkProperties( )".
• getAttribute( ): returns the value of the requested attribute. This method is only available for user-defined format plug-ins. See "getAttribute( )".
• getAllAttributes( ): returns a formatted string for convenient client access. For natively supported formats, the string includes the following list of audio data attributes separated by a comma (,): FileFormat, Encoding, NumberOfChannels, SamplingRate, and SampleSize. Different format plug-ins can return data in any format in this call. For user-defined formats, the string is defined by the format plug-in. See "getAllAttributes( )".

ORDAudio Methods Associated with Processing Audio Data

• processAudioCommand( ): sends commands and related arguments to the format plug-in for processing. This method is available only for user-defined format plug-ins. See "processAudioCommand( )".

For more information on object types and methods, see Oracle9i Database Concepts.

6.3.1 Example Table Definitions

The methods described in this reference chapter show examples based on a test audio table TAUD. Refer to the TAUD table definition that follows when reading through the examples:

TAUD Table Definition

CREATE TABLE TAUD(n NUMBER, aud ORDSYS.ORDAUDIO)
storage (initial 100K next 100K pctincrease 0);

INSERT INTO TAUD VALUES(1, ORDSYS.ORDAudio.init());
INSERT INTO TAUD VALUES(2, ORDSYS.ORDAudio.init());

---

checkProperties( )

Format

checkProperties(ctx IN OUT RAW) RETURN BOOLEAN;

Description

Checks the properties of the stored audio data, including the following audio attributes: sample size, sample rate, number of channels, format, and encoding type.

Parameters

ctx

The format plug-in context information.

Usage Notes

If the format is set to NULL, then the checkProperties( ) method uses the default format plug-in; otherwise, it uses the plug-in specified by the format.

The checkProperties( ) method does not check the MIME type because a file can have multiple correct MIME types and this is not well defined.

Pragmas

None.

Exceptions

AUDIO_PLUGIN_EXCEPTION

This exception is raised if you call the checkProperties( ) method and the audio plug-in raises an exception.

Examples

Check property information for known audio attributes:

DECLARE
  obj ORDSYS.ORDAudio;
  ctx RAW(4000) :=NULL;
BEGIN
  select aud into obj from TAUD where N =1 for update;
  if( obj.checkProperties(ctx) =  TRUE ) then
  DBMS_OUTPUT.put_line('true');
  else
  DBMS_OUTPUT.put_line('false');
  end if;
  EXCEPTION
   WHEN ORDSYS.ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION THEN
    DBMS_OUTPUT.put_line('ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION caught');
   WHEN OTHERS THEN
    DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/

---

getAllAttributes( )

Format

getAllAttributes(

ctx IN OUT RAW,

attributes IN OUT NOCOPY CLOB);

Description

Returns a formatted string for convenient client access. For natively supported formats, the string includes the following list of audio data attributes separated by a comma (,): fileFormat, mimeType, encoding, numberOfChannels, samplingRate, sampleSize, compressionType, and audioDuration. For user-defined formats, the string is defined by the format plug-in.

Parameters

ctx

The format plug-in context information.

attributes

The attributes.

Usage Notes

These audio data attributes are available from the header of the formatted audio data.

Pragmas

None.

Exceptions

AUDIO_PLUGIN_EXCEPTION

This exception is raised if you call the getAllAttributes( ) method and the audio plug-in raises an exception.

Examples

Return all audio attributes for audio data stored in the database:

DECLARE
  obj ORDSYS.ORDAudio;
  tempLob   CLOB;
  ctx RAW(4000) :=NULL;
BEGIN
  SELECT aud INTO obj FROM TAUD  WHERE N=1;
  DBMS_OUTPUT.PUT_LINE('getting comma separated list of all attribs');
  DBMS_OUTPUT.PUT_LINE('-------------------------------------------');
  DBMS_LOB.CREATETEMPORARY(tempLob, FALSE, DBMS_LOB.CALL);
  obj.getAllAttributes(ctx,tempLob);
  DBMS_OUTPUT.put_line(DBMS_LOB.substr(tempLob, DBMS_LOB.getLength(tempLob) , 1));

  EXCEPTION
  WHEN ORDSYS.ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION THEN
  DBMS_OUTPUT.PUT_LINE('ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION caught');

END;
/

---

getAttribute( )

Format

getAttribute(

ctx IN OUT RAW,

name IN VARCHAR2)

RETURN VARCHAR2;

Description

Returns the value of the requested attribute from audio data for user-defined formats only.

Parameters

ctx

The format plug-in context information.

name

The name of the attribute.

Usage Notes

The audio data attributes are available from the header of the formatted audio data.

Audio data attribute information can be extracted from the audio data itself. You can extend support to a format not understood by the ORDAudio object by implementing an ORDPLUGINS.ORDX_<format>_AUDIO package that supports that format. See Section 3.4.13 for more information.

Pragmas

None.

Exceptions

AUDIO_PLUGIN_EXCEPTION

This exception is raised if you call the getAttribute( ) method and the audio plug-in raises an exception.

Examples

Return information for the specified audio attribute for audio data stored in the database:

DECLARE
  obj ORDSYS.ORDAudio;
  res VARCHAR2(4000);
  ctx RAW(4000) :=NULL;
BEGIN
  SELECT aud INTO obj FROM TAUD  WHERE N=1;
  DBMS_OUTPUT.PUT_LINE('getting audio sample size');
  DBMS_OUTPUT.PUT_LINE('---------------------');
  res := obj.getAttribute(ctx,'sample_size');
  EXCEPTION
        WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
         DBMS_OUTPUT.put_line('Source METHOD_NOT_SUPPORTED caught');
        WHEN ORDSYS.ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION THEN
         DBMS_OUTPUT.put_line('SOURCE PLUGIN EXCEPTION caught');
        WHEN ORDSYS.ORDAudioExceptions.METHOD_NOT_SUPPORTED THEN
         DBMS_OUTPUT.put_line('AUDIO METHOD_NOT_SUPPORTED EXCEPTION caught');
        WHEN ORDSYS.ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION THEN
         DBMS_OUTPUT.put_line('AUDIO PLUGIN EXCEPTION caught');
        WHEN OTHERS THEN
         DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

---

getAudioDuration( )

Format

getAudioDuration( ) RETURN INTEGER;

Description

Returns the value of the audioDuration attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(getAudioDuration, WNDS,
WNPS, RNDS, RNPS)

Exceptions

None.

Examples

See the example in setProperties( ).

---

getContentLength( )

Format

getContentLength(ctx IN OUT RAW) RETURN INTEGER;

Description

Returns the length of the audio data content stored in the source.

Parameters

ctx

The source plug-in context information.

Usage Notes

This method is not supported for all source types. For example, HTTP type sources do not support this method. If you want to implement this call for HTTP type sources, you must define your own modified HTTP source type and implement this method on it.

Pragmas

PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS,
WNPS, RNDS, RNPS)

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the getContentLength( ) method and the value of srcType is NULL and data is not stored locally in the BLOB.

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

This exception is raised if you call the getContentLength( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

See the example in import( ).

---

getCompressionType( )

Format

getCompressionType( ) RETURN VARCHAR2;

Description

Returns the value of the compressionType attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(getCompressionType, WNDS,
WNPS, RNDS, RNPS)

Exceptions

None.

Examples

See the example in setProperties( ).

---

getContentInLob( )

Format

getContentInLob(

ctx IN OUT RAW,

dest_lob IN OUT NOCOPY BLOB,

mimeType OUT VARCHAR2,

format OUT VARCHAR2);

Description

Copies data from a data source into the specified BLOB. The BLOB must not be the BLOB in source.localData.

Parameters

ctx

The source plug-in context information.

dest_lob

The LOB in which to receive data.

mimeType

The MIME type of the data; this may or may not be returned.

format

The format of the data; this may or may not be returned.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the getContentInLob( ) method and the value of srcType is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the getContentInLob( ) method and this method is not supported by the source plug-in being used.

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

This exception is raised if you call the getContentInLob( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Get data from a data source and put it into the specified BLOB:

DECLARE
 obj ORDSYS.ORDAudio;
 tempBLob BLOB;
 mimeType VARCHAR2(4000);
 format VARCHAR2(4000);
 ctx RAW(4000) :=NULL;
BEGIN
 SELECT aud INTO obj FROM TAUD WHERE N = 1 ;
 if(obj.isLocal) then
   DBMS_OUTPUT.put_line('local is true');
 end if;
 DBMS_LOB.CREATETEMPORARY(tempBLob, true, 10);
 obj.getContentInLob(ctx,tempBLob, mimeType,format);
 DBMS_OUTPUT.PUT_LINE(TO_CHAR(DBMS_LOB.getLength(tempBLob)));
 EXCEPTION
  WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.put_line('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
  WHEN OTHERS THEN
   DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/

---

getDescription( )

Format

getDescription( ) RETURN VARCHAR2;

Description

Returns the description of the audio data.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(getDescription, WNDS, WNPS, RNDS, RNPS)

Exceptions

DESCRIPTION_IS_NOT_SET

This exception is raised if you call the getDescription( ) method and the description is not set.

Examples

See the example in setDescription( ).

---

getEncoding( )

Format

getEncoding( ) RETURN VARCHAR2;

Description

Returns the value of the encoding attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(getEncoding, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

See the example in setProperties( ).

---

getFormat( )

Format

getFormat( ) RETURN VARCHAR2;

Description

Returns the value of the format attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(getFormat, WNDS, WNPS, RNDS, RNPS)

Exceptions

AUDIO_FORMAT_IS_NULL

This exception is raised if you call the getFormat( ) method and the value for format is NULL.

Examples

See the example in setProperties( ).

---

getNumberOfChannels( )

Format

getNumberOfChannels( ) RETURN INTEGER;

Description

Returns the value of the numberOfChannels attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(getNumberOfChannels, WNDS,
WNPS, RNDS, RNPS)

Exceptions

None.

Examples

See the example in setProperties( ).

---

getSampleSize( )

Format

getSampleSize( ) RETURN INTEGER;

Description

Returns the value of the sampleSize attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(getSampleSize, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

See the example in setProperties( ).

---

getSamplingRate( )

Format

getSamplingRate( ) IN INTEGER;

Description

Returns the value of the samplingRate attribute of the audio object. The unit is Hz.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(getSamplingRate, WNDS,
WNPS, RNDS, RNPS)

Exceptions

None.

Examples

See the example in setProperties( ).

---

import( )

Format

import(ctx IN OUT RAW);

Description

Transfers audio data from an external audio data source to a local source (localData) within an Oracle database.

Parameters

ctx

The source plug-in context information.This must be allocated. You must call the openSource( ) method; see the introduction to this chapter for more information.

Usage Notes

Use the setSource( ) method to set the external source type, location, and name prior to calling the import( ) method.

You must ensure that the directory exists or is created before you use this method for srcType 'file'.

After importing data from an external audio data source to a local source (within an Oracle database), the source information remains unchanged (that is, pointing to the source from where the data was imported).

Invoking this method implicitly calls the setUpdateTime( ) and setLocal methods.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the import( ) method and the value of srcType is NULL.

ORDSourceExceptions.NULL_SOURCE

This exception is raised if you call the import( ) method and the value of dlob is NULL.

ORDSourceExceptionsMETHOD_NOT_SUPPORTED

This exception is raised if you call the import( ) method and the import( ) method is not supported by the source plug-in being used.

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

This exception is raised if you call the import( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Import audio data from an external audio data source into the local source:

DECLARE
  obj ORDSYS.ORDAudio;
  ctx RAW(4000) :=NULL;
BEGIN
  SELECT aud INTO obj FROM TAUD  WHERE N=1 FOR UPDATE;
  DBMS_OUTPUT.PUT_LINE('setting and getting source');
  DBMS_OUTPUT.PUT_LINE('--------------------------');
  -- set source to a file
  obj.setSource('file','AUDIODIR','testaud.dat');
  -- get source information
  DBMS_OUTPUT.PUT_LINE(obj.getSource());
  -- import data
  obj.import(ctx);
  -- check size
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getContentLength(ctx)));
  DBMS_OUTPUT.PUT_LINE(obj.getSource());
  DBMS_OUTPUT.PUT_LINE('deleting contents');
  DBMS_OUTPUT.PUT_LINE('-----------------');
  obj.deleteContent();
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getContentLength(ctx)));
  UPDATE TAUD SET aud=obj WHERE N=1;
  COMMIT;
END;
/

---

importFrom( )

Format

importFrom(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Transfers audio data from the specified external audio data source to a local source (localData) within an Oracle database.

Parameters

ctx

The source plug-in context information. This must be allocated. You must call the openSource( ) method; see the introduction to this chapter for more information.

source_type

The source type of the audio data.

source_location

The location from where the audio data is to be imported.

source_name

The name of the audio data.

Usage Notes

This method is similar to the import( ) method except the source information is specified as parameters to the method instead of separately.

You must ensure that the directory exists or is created before you use this method for srcType 'file'.

After importing data from an external audio data source to a local source (within an Oracle database), the source information (that is, pointing to the source from where the data was imported) is set to the input values.

Invoking this method implicitly calls the setUpdateTime( ) and setLocal methods.

Pragmas

None.

Exceptions

ORDSourceExceptions.NULL_SOURCE

This exception is raised if you call the importFrom( ) method and the value of dlob is NULL.

ORDSourceExceptionsMETHOD_NOT_SUPPORTED

This exception is raised if you call the importFrom( ) method and this method is not supported by the source plug-in being used.

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

This exception is raised if you call the importFrom( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Import audio data from the specified external data source into the local source:

DECLARE
  obj ORDSYS.ORDAudio;
  ctx RAW(4000) :=NULL;
BEGIN
  SELECT aud INTO obj FROM TAUD  WHERE N=1 FOR UPDATE;
  DBMS_OUTPUT.PUT_LINE('setting and getting source');
  DBMS_OUTPUT.PUT_LINE('--------------------------');
  -- set source to a file
  -- import data
  obj.importFrom(ctx,'file','AUDIODIR','testaud.dat');
  -- check size
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getContentLength(ctx)));
  DBMS_OUTPUT.PUT_LINE(obj.getSource());
  DBMS_OUTPUT.PUT_LINE('deleting contents');
  DBMS_OUTPUT.PUT_LINE('-----------------');
  obj.deleteContent();
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getContentLength(ctx)));
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(DBMS_LOB.GETLENGTH(obj.getContent())));
  UPDATE TAUD SET aud=obj WHERE N=1;
  COMMIT;
  EXCEPTION
        WHEN ORDSYS.ORDAudioExceptions.METHOD_NOT_SUPPORTED THEN
        DBMS_OUTPUT.PUT_LINE('Source not specified');
END;
/

---

processAudioCommand( )

Format

processAudioCommand(

ctx IN OUT RAW,

cmd IN VARCHAR2,

arguments IN VARCHAR2,

result OUT RAW)

RETURN RAW;

Description

Allows you to send a command and related arguments to the format plug-in for processing.

Parameters

ctx

The format plug-in context information.

cmd

Any command recognized by the format plug-in.

arguments

The arguments of the command.

result

The result of calling this function returned by the format plug-in.

Usage Notes

Use this method to send any audio commands and their respective arguments to the format plug-in. Commands are not interpreted; they are taken and passed through to a format plug-in to be processed.

If the format is set to NULL, then the processAudioCommand( ) method uses the default format plug-in; otherwise, it uses your user-defined format plug-in.

You can extend support to a format that is not understood by the ORDAudio object by preparing an ORDPLUGINS.ORDX_<format>_AUDIO package that supports that format. See Section 3.4.13 for more information.

Pragmas

None.

Exceptions

AUDIO_PLUGIN_EXCEPTION

This exception is raised if you call the processAudioCommand( ) method and the audio plug-in raises an exception.

Examples

Process a set of commands:

DECLARE
  obj ORDSYS.ORDAudio;
  res RAW(4000);
  result RAW(4000);
  command VARCHAR(4000);
  argList VARCHAR(4000);
  ctx RAW(4000) :=NULL;
BEGIN
  select aud into obj from TAUD where N =1 for UPDATE;
  -- assign command
  -- assign argList
  res := obj.processAudioCommand (ctx, command, argList, result);
  UPDATE TAUD SET aud=obj WHERE N=1 ;
  COMMIT;
  EXCEPTION
        WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
         DBMS_OUTPUT.put_line('Source METHOD_NOT_SUPPORTED caught');
        WHEN ORDSYS.ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION THEN
         DBMS_OUTPUT.put_line('SOURCE PLUGIN EXCEPTION caught');
        WHEN ORDSYS.ORDAudioExceptions.METHOD_NOT_SUPPORTED THEN
         DBMS_OUTPUT.put_line('AUDIO METHOD_NOT_SUPPORTED EXCEPTION caught');
        WHEN ORDSYS.ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION THEN
         DBMS_OUTPUT.put_line('AUDIO PLUGIN EXCEPTION caught');
        WHEN OTHERS THEN
         DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/

---

setAudioDuration( )

Format

setAudioDuration(knownAudioDuration IN INTEGER);

Description

Sets the value of the audioDuration attribute of the audio object.

Parameters

knownAudioDuration

A known audio duration.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

NULL_INPUT_VALUE

This exception is raised if you call the setAudioDuration( ) method and the value for the knownAudioDuration parameter is NULL.

Examples

See the example in setProperties( ).

---

setCompressionType( )

Format

setCompressionType(knownCompressionType IN VARCHAR2);

Description

Sets the value of the compressionType attribute of the audio object.

Parameters

knownCompressionType

A known compression type.

Usage Notes

The value of the compressionType always matches that of the encoding value because in many audio formats, encoding and compression type are tightly integrated. See Appendix A for more information.

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

NULL_INPUT_VALUE

This exception is raised if you call the setCompressionType( ) method and the value for the knownCompressionType parameter is NULL.

Examples

See the example in setProperties( ).

---

setDescription( )

Format

setDescription (user_description IN VARCHAR2);

Description

Sets the description of the audio data.

Parameters

user_description

The description of the audio data.

Usage Notes

Each audio object may need a description to help some client applications. For example, a Web-based client can show a list of audio descriptions from which a user can select one to access the audio data.

Web-access components and other client components provided with Oracle interMedia make use of this description attribute to present audio data to users.

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

None.

Examples

Set the description attribute for some audio data:

DECLARE
  obj ORDSYS.ORDAudio;
BEGIN
  SELECT aud INTO obj FROM TAUD  WHERE N=1 FOR UPDATE;
  DBMS_OUTPUT.PUT_LINE('writing title');
  DBMS_OUTPUT.PUT_LINE('-------------');
  obj.setDescription('audio1.wav');
  DBMS_OUTPUT.PUT_LINE(obj.getDescription());
  UPDATE TAUD SET aud=obj WHERE N=1;
  COMMIT;
END;
/

---

setEncoding( )

Format

setEncoding(knownEncoding IN VARCHAR2);

Description

Sets the value of the encoding attribute of the audio object.

Parameters

knownEncoding

A known encoding type.

Usage Notes

The value of encoding always matches that of the compressionType value because in many audio formats, encoding and compression type are tightly integrated. See Appendix A for more information.

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

NULL_INPUT_VALUE

This exception is raised if you call the setEncoding( ) method and the value for the knownEncoding parameter is NULL.

Examples

See the example in setProperties( ).

---

setFormat( )

Format

setFormat(knownFormat IN VARCHAR2);

Description

Sets the format attribute of the audio object.

Parameters

knownFormat

The known format of the audio data to be set in the audio object.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

NULL_INPUT_VALUE

This exception is raised if you call the setFormat( ) method and the value for the knownFormat parameter is NULL.

Examples

Set the format for some audio data:

DECLARE
  obj ORDSYS.ORDAudio;
BEGIN
  select aud into obj from TAUD where N =1 for update;
  obj.setFormat('AUFF');
  obj.setEncoding('MULAW');
  obj.setNumberOfChannels(1);
  obj.setSamplingRate(8);
  obj.setSampleSize(8);
  obj.setCompressionType('8BITMONOAUDIO');
  obj.setAudioDuration(16);
  DBMS_OUTPUT.put_line('format: ' || obj.getformat);
  DBMS_OUTPUT.put_line('encoding: ' || obj.getEncoding);
  DBMS_OUTPUT.put_line('numberOfChannels: ' || TO_CHAR(obj.getNumberOfChannels));
  DBMS_OUTPUT.put_line('samplingRate: ' || TO_CHAR(obj.getSamplingRate));
  DBMS_OUTPUT.put_line('sampleSize: ' || TO_CHAR(obj.getSampleSize));
  DBMS_OUTPUT.put_line('compressionType : ' || obj.getCompressionType);
  DBMS_OUTPUT.put_line('audioDuration: ' || TO_CHAR(obj.getAudioDuration));
  COMMIT;
  EXCEPTION
   WHEN ORDSYS.ORDAudioExceptions.NULL_INPUT_VALUE THEN
    DBMS_OUTPUT.put_line('ORDAudioExceptions.NULL_INPUT_VALUE caught');
   WHEN OTHERS THEN
    DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/

---

setKnownAttributes( )

Format

setKnownAttributes(

knownFormat IN VARCHAR2,

knownEncoding IN VARCHAR2,

knownNumberOfChannels IN INTEGER,

knownSamplingRate IN INTEGER,

knownSamleSize IN INTEGER,

knownCompressionType IN VARCHAR2,

knownAudioDuration IN INTEGER);

Description

Sets the known audio attributes for the audio object.

Parameters

knownFormat

The known format.

knownEncoding

The known encoding type.

knownNumberOfChannels

The known number of channels.

knownSamplingRate

The known sampling rate.

knownSampleSize

The known sample size.

knownCompressionType

The known compression type.

knownAudioDuration

The known audio duration.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

None.

Examples

Set the known attributes for the audio data.

DECLARE
  obj ORDSYS.ORDAudio;
BEGIN
  select aud into obj from TAUD where N =1 for update;
  obj.setKnownAttributes('AUFF','MULAW', 1, 8, 8, '8BITMONOAUDIO',16);
  DBMS_OUTPUT.put_line('format: ' || obj.getformat());
  DBMS_OUTPUT.put_line('encoding: ' || obj.getEncoding());
  DBMS_OUTPUT.put_line('numberOfChannels: ' || TO_CHAR(obj.getNumberOfChannels()));
  DBMS_OUTPUT.put_line('samplingRate: ' || TO_CHAR(obj.getSamplingRate()));
  DBMS_OUTPUT.put_line('sampleSize: ' || TO_CHAR(obj.getSampleSize()));
  DBMS_OUTPUT.put_line('compressionType : ' || obj.getCompressionType());
  DBMS_OUTPUT.put_line('audioDuration: ' || TO_CHAR(obj.getAudioDuration()));
  COMMIT;
  EXCEPTION
   WHEN ORDSYS.ORDAudioExceptions.METHOD_NOT_SUPPORTED THEN
    DBMS_OUTPUT.put_line('ORDAudioExceptions.METHOD_NOT_SUPPORTED caught');
   WHEN OTHERS THEN
    DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/

---

setNumberOfChannels( )

Format

setNumberOfChannels(knownNumberOfChannels IN INTEGER);

Description

Sets the value of the numberOfChannels attribute for the audio object.

Parameters

knownNumberOfChannels

A known number of channels.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

NULL_INPUT_VALUE

This exception is raised if you call the setNumberOfChannels( ) method and the value for the knownNumberOfChannels parameter is NULL.

Examples

See the example in setProperties( ).

---

setProperties( )

Format

setProperties(ctx IN OUT RAW,

setComments IN BOOLEAN);

Description

Reads the audio data to get the values of the object attributes and then stores them in the object attributes. This method sets the properties for the following attributes of the audio data: format, encoding type, number of channels, sampling rate, and sample size. It populates the comments field of the object with a rich set of format and application properties in XML form if the value of the setComments parameter is TRUE.

Parameters

ctx

The format plug-in context information.

setComments

If the value is TRUE, then the comments field of the object is populated with a rich set of format and application properties of the audio object in XML form, identical to what is provided by the interMedia Annotator utility; otherwise, if the value is FALSE, the comments field of the object remains unpopulated. The default value is FALSE.

Usage Notes

If the property cannot be extracted from the media source, then the respective attribute is set to NULL.

If the format is set to NULL, then the setProperties( ) method uses the default format plug-in; otherwise, it uses the plug-in specified by the format.

Pragmas

None.

Exceptions

AUDIO_PLUGIN_EXCEPTION

This exception is raised if you call the setProperties( ) method and the audio plug-in raises an exception.

Examples

Set the property information for known audio attributes:

DECLARE
  obj ORDSYS.ORDAudio;
  ctx RAW(4000) :=NULL;
BEGIN
  select aud into obj from TAUD where N =1 for update;
  obj.setProperties(ctx,FALSE);
  --DBMS_OUTPUT.put_line('format: ' || obj.getformat());
  DBMS_OUTPUT.put_line('encoding: ' || obj.getEncoding());
  DBMS_OUTPUT.put_line('numberOfChannels: ' || TO_CHAR(obj.getNumberOfChannels()));
  DBMS_OUTPUT.put_line('samplingRate: ' || TO_CHAR(obj.getSamplingRate()));
  DBMS_OUTPUT.put_line('sampleSize: ' || TO_CHAR(obj.getSampleSize()));
  update  TAUD set aud = obj where  N =1 ;
  COMMIT;
  EXCEPTION
   WHEN ORDSYS.ORDAudioExceptions.METHOD_NOT_SUPPORTED THEN
    DBMS_OUTPUT.put_line('ORDAudioExceptions.METHOD_NOT_SUPPORTED caught');
   WHEN OTHERS THEN
    DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/

---

setSamplingRate( )

Format

setSamplingRate(knownSamplingRate IN INTEGER);

Description

Sets the value of the samplingRate attribute of the audio object. The unit is Hz.

Parameters

knownSamplingRate

A known sampling rate.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

NULL_INPUT_VALUE

This exception is raised if you call the setSamplingRate( ) method and the value for the knownSamplingRate parameter is NULL.

Examples

See the example in setProperties( ).

---

setSampleSize( )

Format

setSampleSize(knownSampleSize IN INTEGER);

Description

Sets the value of the sampleSize attribute of the audio object.

Parameters

knownSampleSize

A known sample size.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

NULL_INPUT_VALUE

This exception is raised if you call the setSampleSize( ) method and the value for the knownSampleSize parameter is NULL.

Examples

See the example in setProperties( ).

6.4 Packages or PL/SQL Plug-ins

This section presents reference information on the packages or PL/SQL plug-ins provided. Table 6-1 describes the PL/SQL plug-in packages provided in the ORDPLUGINS schema.

Table 6-1 PL/SQL Plug-ins Provided in the ORDPLUGINS Schema

PL/SQL Plug-in Packages	Audio Format	MIME Type
ORDPLUGINS.ORDX_DEFAULT_AUDIO	<format>	Dependent on file format
ORDPLUGINS.ORDX_AUFF_AUDIO	AUFF	audio/basic
ORDPLUGINS.ORDX_AIFF_AUDIO	AIFF	audio/x-aiff
ORDPLUGINS.ORDX_AIFC_AUDIO	AIFC	audio/x-aiff
ORDPLUGINS.ORDX_WAVE_AUDIO	WAVE	audio/x-wave
ORDPLUGINS.ORDX_MPGA_AUDIO	MPGA	audio/mpeg

Section 6.4.1 describes the ORDPLUGINS.ORDX_DEFAULT_AUDIO package, the methods supported, and the level of support. Note that the methods supported and the level of support for the other PL/SQL plug-in packages described in Table 6-1 are identical for all plug-in packages, therefore, refer to Section 6.4.1.

6.4.1 ORDPLUGINS.ORDX_DEFAULT_AUDIO Package

Use the following provided ORDPLUGINS.ORDX_DEFAULT_AUDIO package as a guide in developing your own ORDPLUGINS.ORDX_<format>_AUDIO audio format package. This package sets the mimeType field in the setProperties( ) method with a MIME type value that is dependent on the file format.

CREATE OR REPLACE PACKAGE ORDX_DEFAULT_AUDIO
authid current_user
AS 
--AUDIO ATTRIBUTES ACCESSORS
--Deprecated Functions Deprecated in Release 8.1.6 Begin Here 
FUNCTION getFormat(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
                RETURN VARCHAR2;
FUNCTION getEncoding(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
                RETURN VARCHAR2;
FUNCTION getNumberOfChannels(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
                RETURN INTEGER;
FUNCTION getSamplingRate(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
                RETURN INTEGER;
FUNCTION getSampleSize(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
                RETURN INTEGER;
FUNCTION getCompressionType(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
                RETURN VARCHAR2;
FUNCTION getAudioDuration(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
                RETURN INTEGER;
--Deprecated Functions Deprecated in Release 8.1.6 End Here 

PROCEDURE setProperties(ctx IN OUT RAW, 
                        obj IN OUT NOCOPY ORDSYS.ORDAudio,
                        setComments IN NUMBER := 0);
FUNCTION checkProperties(ctx IN OUT RAW, obj IN OUT ORDSYS.ORDAudio)
                RETURN NUMBER;
FUNCTION getAttribute(ctx IN OUT RAW,
                      obj IN ORDSYS.ORDAudio,
                      name IN VARCHAR2) RETURN VARCHAR2;
PROCEDURE getAllAttributes(ctx IN OUT RAW, 
                           obj IN ORDSYS.ORDAudio, 
                           attributes IN OUT NOCOPY CLOB);
--AUDIO PROCESSING METHODS
FUNCTION processCommand(ctx       IN OUT RAW,
                        obj       IN OUT NOCOPY ORDSYS.ORDAudio,
                        cmd       IN VARCHAR2,
                        arguments IN VARHAR2,
                        result    OUT RAW)
         RETURN RAW;

PRAGMA RESTRICT_REFERENCES(getFormat, WNDS, WNPS, RNDS, RNPS);
PRAGMA RESTRICT_REFERENCES(getEncoding, WNDS, WNPS, RNDS, RNPS);
PRAGMA RESTRICT_REFERENCES(getNumberOfChennels, WNDS, WNPS, RNDS, RNPS);
PRAGMA RESTRICT_REFERENCES(getSamplingRate, WNDS, WNPS, RNDS, RNPS);
PRAGMA RESTRICT_REFERENCES(getSampleSize, WNDS, WNPS, RNDS, RNPS);
PRAGMA RESTRICT_REFERENCES(getCompressionType, WNDS, WNPS, RNDS, RNPS);
PRAGMA RESTRICT_REFERENCES(getAttribute, WNDS, WNPS, RNDS, RNPS);
PRAGMA RESTRICT_REFERENCES(getAudioDuration, WNDS, WNPS, RNDS, RNPS);

END;
/

Table 6-2 shows the methods supported in the
ORDPLUGINS.ORDX_DEFAULT_AUDIO package and the exceptions raised if you call a method that is not supported.

Table 6-2 Methods Supported in the ORDPLUGINS.ORDX_DEFAULT_AUDIO Package 

Name of Method	Level of Support
getFormat	Supported; if the source is local, get the attribute and return the file format, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDAudioExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
getEncoding	Supported; if the source is local, get the attribute and return the encoding, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDAudioExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
getNumberOfChannels	Supported; if the source is local, get the attribute and return the number of channels, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDAudioExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
getSamplingRate	Supported; if the source is local, get the attribute and return the sampling rate, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDAudioExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
getSampleSize	Supported; if the source is local, get the attribute and return the sample size, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDAudioExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
getCompressionType	Supported; if the source is local, get the attribute and return the compression type, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDAudioExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
getAudioDuration	Supported; if the source is local, get the attribute and return the audio duration, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDAudioExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
setProperties	Supported; if the source is local, process the local data and set the properties, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; if the source is a BFILE, then process the BFILE and set the properties; if the source is neither local nor a BFILE, get the media content into a temporary LOB, process the data, and set the properties.
checkProperties	Supported; if the source is local, process the local data and check the properties, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; if the source is a BFILE, then process the BFILE and check the properties; if the source is neither local nor a BFILE, get the media content into a temporary LOB, process the data, and check the properties.
getAttribute	Not supported - raises exceptions: METHOD_NOT_SUPPORTED and AUDIO_PLUGIN_EXCEPTION.
getAllAttributes	Supported; if the source is local, get the attributes and return them, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; otherwise, if the source is external, raise an ORDSYS.ORDAudioExceptions.LOCAL_DATA_SOURCE_REQUIRED exception.
processCommand	Not supported - raises exceptions: METHOD_NOT_SUPPORTED and AUDIO_PLUGIN_EXCEPTION.

6.4.2 Extending interMedia to Support a New Audio Data Format

Extending interMedia to support a new audio data format consists of four steps:

1. Design your new audio data format.
2. Implement your new audio data format and name it, for example, ORDX_MY_AUDIO.SQL.
3. Install your new ORDX_MY_AUDIO.SQL plug-in in the ORDPLUGINS schema.
4. Grant EXECUTE privileges on your new plug-in, for example, ORDX_MY_AUDIO.SQL plug-in, to PUBLIC.

Section 3.1.12 briefly describes how to extend interMedia to support a new audio data format and describes the interface. A package body listing is provided in Example 6-1 to assist you in this operation. Add your variables to the places that say "--Your variables go here" and add your code to the places that say "--Your code goes here".

See Section F.1 for more information on installing your own audio format plug-in and running the sample scripts provided.

Example 6-1 Show the Package Body for Extending Support to a New Audio
Data Format

CREATE OR REPLACE PACKAGE BODY ORDX_MY_AUDIO
AS
  --AUDIO ATTRIBUTES ACCESSORS
  FUNCTION  getFormat(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
  RETURN VARCHAR2
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  FUNCTION  getEncoding(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
  RETURN VARCHAR2
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  FUNCTION  getNumberOfChannels(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
  RETURN INTEGER
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  FUNCTION  getSamplingRate(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
  RETURN INTEGER
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  FUNCTION  getSampleSize(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
  RETURN INTEGER
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  FUNCTION  getCompressionType(ctx IN OUT RAW, obj IN ORDSYS.ORDAudio)
  RETURN VARCHAR2
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  FUNCTION  getAudioDuration(ctx IN OUT RAW,
                             obj IN ORDSYS.ORDAudio)
  RETURN INTEGER
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  PROCEDURE setProperties(ctx IN OUT RAW,
                          obj IN OUT NOCOPY ORDSYS.ORDAudio,
                          setComments IN NUMBER :=0)
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  FUNCTION checkProperties(ctx IN OUT RAW, obj IN OUT ORDSYS.ORDAudio)
  RETURN NUMBER
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  FUNCTION  getAttribute(ctx IN OUT RAW,
                         obj IN ORDSYS.ORDAudio,
                         name IN VARCHAR2)
  RETURN VARCHAR2
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  PROCEDURE getAllAttributes(ctx IN OUT RAW,
                             obj IN ORDSYS.ORDAudio,
                             attributes IN OUT NOCOPY CLOB)
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
  -- AUDIO PROCESSING METHODS
  FUNCTION  processCommand(
                                 ctx       IN OUT RAW,
                                 obj       IN OUT NOCOPY ORDSYS.ORDAudio,
                                 cmd       IN VARCHAR2,
                                 arguments IN VARCHAR2,
                                 result    OUT RAW)
  RETURN RAW
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
END;
/
show errors;