Copyright (c) 2004,2008 Oracle. All Rights Reserved. Oracle Multimedia Custom DataSource Plug-in 2.0 for Microsoft Windows Media Services ================================================================ This file describes the steps required to install, configure and use the Oracle Multimedia Custom DataSource Plug-in for Microsoft Window Media Service. The Multimedia Plug-in enables Microsoft Windows Media Services to stream multimedia content to a client directly from an Oracle Database. ======== Contents ======== About the Plug-in Requirements What's New Installation Enabling the Plug-in Storing the Database Connection Credentials in Oracle Wallet Configuring Oracle Mount Points Configuring Windows Media Server Publishing Point Examples Testing the Plug-in Upgrading from Previous Version of Plug-in Deinstallation Notes Error Messages Troubleshooting ================== About the Plug-in ================== Oracle Multimedia Custom DataSource Plug-in for Microsoft Windows Media Services (Plug-in) enables Microsoft Windows Media servers to stream multimedia content to a client directly from Oracle Database. This package also includes a Plug-in Property Page that can be accessed from the Windows Media Services Administrative interfaces. The Plug-in Property Page allows users to inspect, define, and edit the Plug-in mount points that map to media content in an Oracle Database. The Plug-in mount points are used to configure the source URL of a server publishing point, from which a Microsoft Windows Media Player client requests media content stored in an Oracle Database. Only Windows Media Format files (ASF, WMA, WMV) can be played from the Oracle Multimedia Custom DataSource Plug-in. ============ Requirements ============ The requirements for running Oracle Multimedia Custom DataSource Plug-in for Microsoft Windows Media Services are as follows: 1) Oracle Database Oracle Database Release 10g or 11g Consult your platform-specific installation documentation for specific information on operating system version and service pack requirements. 2) Oracle Database Client Oracle 11g Client Release 11.1.0.6 Consult your Oracle installation documentation for specific information about the required service packs and minimum hardware requirements. 3) Microsoft 2003 Server Enterprise Edition Microsoft Windows Media Services 9 series must be installed on this server. ========== What's New ========== Version 2.0 of Oracle Multimedia Custom DataSource Plug-in for Microsoft Windows Media Services includes the following changes from version 1.0 1. Support for storing external passwords using Oracle Wallet has been added. Previous versions of the plug-in stored database connection information (such as database, username, password) in the Windows Media Server configuration file through the Custom DataSource Plug-in Property Page. This information is now stored securely in an encrypted form using Oracle Wallet. The Mountpoint configuration parameters "Database", "UserName" and "Password" are deprecated. The parameter "Database Connect String" is used to specify the database connection. See "Storing the Database Connection Credentials in Oracle Wallet" for more information. The previous changes do not require changes to your streaming media application. They are limited to the definition of the Oracle mount point in the Custom DataSource Plug-in Property Page. Existing media URLs will continue to work without changes. One extra step is needed. You need to store database connection credentials in Oracle Wallet during the Oracle Multimedia Plug-in configuration. Read this file carefully before attempting to use the new plug-in. If you are upgrading a previous version of the plug-in, read "Upgrading from Previous Version of Plug-in". ============ Installation ============ 1. Run the program, Setup.exe and specify a directory in which to install the Plug-in. 2. Select "Everyone" during the installation. 3. Restart Windows Media Services to load the installed Plug-in. ===================== Enabling the Plug-in ===================== To enable the Plug-in: 1. Start the Windows Media Services Administrative interface. 2. Click the server you want to configure from the console tree on the left pane of the Windows Media Service user interface. 3. Click the Properties tab on the detail pane on the right. 4. Check Show all plug-in categories. 5. Select the Data source from the Category list on the left. 6. Select Oracle Multimedia Custom DataSource Plug-in for WMS from the Plug-in list on the right. 7. Click Enable to enable the Plug-in. ============================================================ Storing the Database Connection Credentials in Oracle Wallet ============================================================ Oracle Wallet is used to store password credentials for connecting to a database. An Oracle Wallet is a secure software container that stores the authentication and signing credentials needed for a user to log in. It is installed as part of Oracle Database Client. The following steps assume that the directory %ORACLE_HOME%\bin is in the execution PATH variable. The variable %ORACLE_HOME% represents the location of the Oracle product install. 1. Create a wallet on the Oracle Database Client (the Windows Media host), using the following command at prompt: mkstore -wrl -create password: where, : the path to the directory where you want to create and store the wallet. Enter the wallet password to access the wallet you created in response to the "password" prompt. For example: mkstore -wrl c:\users\smith\wallets -create 2. Create a database connection credential in the wallet, using the following command at prompt: mkstore -wrl -createCredential Your secret/Password is missing in the command line Enter your secret/Password: Re-enter your secret/Password: Enter wallet password: where, : the path to the directory where you stored the wallet you created in Step 1. : the TNS alias you use to specify the database in the tnsnames.ora file, or any service name you use to identify the database on an Oracle network. The syntax is used to specify the database connection information in the "Database Connect String" field of the Plug-in mountpoint property page. Note: Each database user account must have its own unique connection string. You cannot create one connection string for multiple database users. : the database login credential. At the prompt "secret/Password", enter the database user password for this user. For example: mkstore -wrl c:\users\smith\wallets -createCredential orcl scott 3. Edit the file %ORACLE_HOME%\network\admin\sqlnet.ora file. Create a WALLET_LOCATION definition and set it to the directory location of the wallet you created in Step 1. WALLET_LOCATION = (SOURCE = (METHOD = FILE) (METHOD_DATA = (DIRECTORY = ) ) ) where : the path to the directory where you stored the wallet you created in Step 1. 4. In the client sqlnet.ora file, enter the SQLNET.WALLET_OVERRIDE parameter and set it to TRUE, as follows: SQLNET.WALLET_OVERRIDE = TRUE This setting causes all CONNECT /@db_connect_string statements to use the information in the wallet at the specified location to authenticate to Oracle databases. 5. Confirm that the database connection credential has been created and is working by connecting to the database without providing a username and password: sqlplus /@ where, must be identical to the specified in the -createCredential command as shown in Step 2. See the Oracle document "Oracle Database Security Guide" for more information about Oracle Wallet. =============================== Configuring Oracle Mount Points =============================== An Oracle mount point specifies all the information that is required by the Custom DataSource Plug-in to retrieve the media content associated with a URL. One or more Oracle mount points can be defined and managed using the Property Page of the Plug-in from the WMS Administrative interfaces. Online help is available by clicking Help after you open the Plug-in Property Page. To open the Property Page for the Plug-in: 1. Click the server you want to configure from the console tree on the left pane of the Windows Media Service user interface. 2. Click the Properties tab on the detail pane on the right. 3. Check Show all plug-in categories. 4. Select the Data source from the category list on the left. 5. Select Oracle Multimedia Custom DataSource Plug-in For WMS from the Plug-in list on the right. 6. Click View properties to open the Plug-in Property Page. To add an Oracle mount point: 1. On the Plug-in Property Page, click Add to open "Add Mount Point" dialog box. 2. Enter the new mount point name in the Mount Point Name field. The name must be unique and should not contain the characters: "/" or "\". 3. Enter a description for this new mount point in the Description field. 4. In the Database Connect String field, specify the string to use to connect to Oracle Database that contains the content for this mount point. This string must be identical to the specified in the -createCredential command when creating the database connection credential in Oracle Wallet. See "Storing the Database Connection Credentials in Oracle Wallet" for more information about . Only one connect string is permitted for each database user. 5. In the PL/SQL Procedure Name field, enter the name of the PL/SQL stored procedure to use to fetch the content from the database. This name may be a simple procedure name, (such as getVideo), a schema qualified name, (such as SCOTT.getVideo), a synonym, or any other valid syntax for naming a stored procedure. The PL/SQL procedure must define an output parameter named DATA of type BLOB or BFILE. The procedure can define an additional optional output(OUT) parameter that denotes the Plug-in the MIME type of the media. The parameters must use the names and data types shown in the following table. Output Parameter SQL type Description Name --------- -------- ----------- DATA BLOB The LOB locator for the media content. Media BFILE content may be stored in a BLOB or a BFILE. MIMETYPE VARCHAR2 The MIME type of the media content. The maximum supported length for this parameter is 128 characters. The PL/SQL procedure can define any number of input parameters. The Plug-in will bind text strings from the request URL to the input parameters in order of input. Be aware of issues that may arise because of type conversion. For example, converting from text to NUMBER or INTEGER data types does not pose a problem. Other data, such as dates, should be input as strings to the PL/SQL procedure and then converted to the appropriate data type within the procedure, (for example: by using the TO_DATE() function). 8. Click OK to close the dialog box. You should see the new mount point from the list box. You do not need to restart Windows Media Services for the change to take effect. To edit an existing Oracle mount point: 1. In the Plug-in Property Page, click the name of the mount point you want to edit from the list of mount points. 2. Click the Properties button to open the Mount Point Properties Dialog box. 3. To change the mount point properties, enter the new values in the appropriate edit boxes. The mount point name cannot be changed. 4. Click Apply to save the changes. 5. Click OK to close the dialog box. You do not need to restart Windows Media Services for the change to take effect. To delete an Oracle mount point: 1. In the Plug-in Property Page, click the name of the mount point you want to delete from the list of mount points. 2. Click Remove. 3. Click Yes. =========================================================== Configuring Windows Media Server Publishing Point =========================================================== To stream the media stored in Oracle Database from a server publishing point, you must define the publishing point's source URL point as "ord://" or "ord:///". Where: : the name of the mount point defined in the Plug-in Property Page. : the input parameters to the PL/SQL procedure specified in the mount point definition. The input parameters are separated by "/". The URL format for WMS client request is determined by the source URL of the publishing point: 1. Publishing point source URL: "ord://", WMS client request URL: mms://// The media to be selected from the database table is determined by the in the WMS client request URL. This setup can be used for on-demand publishing points. 2. Publishing point source URL: "ord:///" WMS client request URL: mms:/// The media to be selected from the database table is determined by the in the publishing point source URL. This setup can be used for on-demand and broadcast publishing points. ======== Examples ======== The following example is a PL/SQL package with two procedures. One procedure retrieves media from a BLOB, the other procedure retrieves media from a BFILE. The table is defined as follows: create table wmsmedia (id integer, media ordsys.ordvideo); create or replace package get_media as procedure from_blob( idin in integer, data out blob, mimetype out varchar2); procedure from_bfile( idin in integer, data out bfile); end get_media; / show errors; create or replace package body get_media as procedure from_blob( idin in integer, data out blob, mimetype out varchar2) is begin -- get the data from the blob select t.media.getContent(), t.media.getMimeType() into data, mimetype from wmsmedia t where id = idin; end from_blob; procedure from_bfile( idin in integer, data out bfile) is begin -- get the data from the bfile select t.media.getBfile(), into data from wmsmedia t where id = idin; end from_bfile; end get_media; Example 1. Getting media from a BLOB through an on-demand publishing point. 1) Mount point definition: Mount Point Name: GetMediaFromBlob Database Connect String:orcl PL/SQL Procedure Name: get_media.from_blob Description: get media from blob. 2) Publishing point definition: Windows Media Server Name: MediaServ1 Publishing point name: OraclePB1 Publishing point type: on-demand source URL: ord://GetMediaFromBlob 3) An example of a URL that accesses the media from this mount point: mms://MediaServ1/OraclePB1/10 When requested, the Plug-in will retrieve media from the BLOB stored in the wmsmedia table with an id equal to 10. Example 2. Getting media from a BFILE through an on-demand publishing point. 1) Mount point definition: Mount Point Name: GetMediaFromBfile Database Connect String:orcl PL/SQL Procedure Name: get_media.from_bfile Description: get media from bfile. 2) Publishing point definition: Windows Media Server Name: MediaServ1 Publishing point name: OraclePB2 Publishing point type: on-demand source URL: ord://GetMediaFromBfile 3) An example of a URL that accesses the media from this mount point: mms://MediaServ1/OraclePB2/10 When requested, the Plug-in will retrieve media from the BFILE stored in the wmsmedia table with an id equal to 10. Example 3. Getting media from a BLOB through a broadcast publishing point. 1) Mount point definition: Mount Point Name: GetMediaFromBlob Database Connect String:orcl PL/SQL Procedure Name: get_media.from_blob Description: get media from blob. 2). Publishing point definition: Windows Media Server Name: MediaServ1 Publishing point name: OraclePB3 Publishing point type: broadcast source URL: ord://GetMediaFromBlob/10 3) An example of a URL that accesses the media from this mount point: mms://MediaServ1/OraclePB3/ Example 4. Stream media from a BLOB using playlist The following example is a playlist file that uses the Plug-in to access the media: ==================== Testing the Plug-in ==================== After the Plug-in is installed, enabled, and the mount point is defined, you can test the Plug-in from the Windows Media Services Administrative interface, as follows 1. Create an on-demand publishing point with the source URL in the following form: ord:/// 2. Click on the created publishing point from the left pane under Publishing Points. 3. Select the Source tab from the right detail pane. 4. Click on the Test stream button to open the test stream dialog box. =========================================== Upgrading from Previous Version of Plug-in =========================================== This section explains how to upgrade from the previous version of the Plug-in. There is no change to the media URLs that access the existing publishing points or to the content source URL that access the Oracle mount point. Follow these steps to upgrade the existing Oracle mount point definition by replacing the database connection information in the previous version of the Plug-in with the database connection information you created using Oracle Wallet. 1. Upgrade the Oracle Database Client software to the version required by this version of the Plug-in. 2. Create the database connection credentials in the Oracle Wallet for each database user that is accessed through the Plug-in mount points. 3. Stop the Windows Media Server and close the Windows Media Services console. 4. Run the install program (Setup.exe) for the Plug-in 2.0. The install program will remove the previous version of the Plug-in and install this version of the Plug-in. 5. Open the Windows Media Services console, and start the Windows Media Server. 6. Open the Property Page for the Plug-in. (see "Configuring Oracle Mount Points" for information about opening the Plug-in Property Page) 7. In Plug-in Property Page, click the name of the mount point you want to upgrade from the list of mount points. 8. Click the Properties button to open the Mount Point Properties Dialog box. 9. If this mount point was defined by the previous version of the Plug-in and needs upgrading, the Mount Point Properties Dialog box will display the Database Service Name and User Name as read-only fields, and then prompt you to enter into the Database Connect String edit box for upgrading. 10. Click Apply to save the changes. 11. Click OK to close the dialog box. You do not need to restart Windows Media Services for the change to take effect. =============== Deinstallation =============== Run program Setup.exe to remove and unregister all the files that were previously installed for the Plug-in. ====== Notes ====== Oracle Multimedia Custom DataSource Plug-in has following limitations: 1. Supports the following media formats only: ASF, WMA, WMV. ============== Error Messages ============== Oracle Multimedia Custom DataSource Plug-in for Windows Media Services uses the IWMSEventLog interface in the WMS SDK to log error information in the Windows Event Viewer. Warning level and error level events can be viewed from the Windows Media Services Administrative Interfaces Troubleshooting on the console tree. Error messages are usually provided in levels. There is always a general high-level error message followed by an optional low-level detailed message. Messages have the following form: Oracle Multimedia Custom DataSource Plug-in for WMS Warning: Error accessing data container Oracle Multimedia Custom DataSource Plug-in for WMS Warning: Oracle Multimedia Custom DataSource Plug-in for WMS Warning: For example, the following entry in an error log indicates that the Plug-in could not log on to Oracle Database because either the username or password was invalid. Oracle Multimedia Custom DataSource Plug-in for WMS Warning: Error accessing data container: ord://mountpoint1/1 Oracle Multimedia Custom DataSource Plug-in for WMS Warning: failed to obtain database session. Oracle Multimedia Custom DataSource Plug-in for WMS Warning: ORA-12154: TNS:could not resolve the connect identifier specified The following sections describe the general error messages produced by the Plug-in and how to diagnose each problem: Errors related to initializing the Plug-in: =========================================== The following errors can occur when the Plug-in is loaded and initialized or when the first URL request is made. "failed to initialize Oracle client module" The plug-in was unable to initialize Oracle client services (OCCI). Check your client installation of Oracle. Check that the proper Oracle libraries are available to the Windows Media Server execution environment. Errors related to request processing: ===================================== The following errors may be encountered when processing a URL request. "failed to parse URL" The plug-in was unable to parse the requested URL. See detailed message. "failed to obtain mount point information" The Plug-in was unable to find the mount point definition using the given mount point name. Check the mount point name in the URL and the definition of the mount point. "failed to obtain database session" The plug-in was unable to log on to Oracle. See detailed message. "failed to find the PL/SQL Procedure %s" The plug-in was unable to find the PL/SQL procedure specified by the plug-in mount point. "bind parameter %s has the wrong direction" The named bind parameter has the wrong direction. Check the definition of the PL/SQL procedure used to retrieve the media. Plug-in API parameters must be output(OUT) direction only. Input parameters must be input(IN) direction only. "bind parameter %s has the wrong type" The named bind parameter has the wrong type. Check the definition of the PL/SQL procedure used to retrieve the media. "bind parameter %s has the wrong direction or type" The named bind parameter has the wrong direction or type. Check the definition of the PL/SQL procedure used to retrieve the media. Plug-in API parameters must be output(OUT) direction only. Input parameters must be input(IN) direction only. "required parameter %s is missing" The named parameter is missing. Check the definition of the PL/SQL procedure used to retrieve the media. "multiple OUT parameter %s defined" There are more OUT parameter defined in the PL/SQL procedure than what is required by the plug-in. "URL parameter input is missing" The PL/SQL procedure used to retrieve the media requires more input data. Not enough parameters were found in the requested URL. Check the URL. "URL parameter inputs are more than expected" There are more input data passed to the PL/SQL procedure used to retrieve the media. Check the URL. "LOB is null or empty" The LOB that should contain the data is null or empty. Check the detailed message. "read failure" A read operation on the LOB locator failed. Check the detailed message. Miscellaneous errors ==================== "out of memory" The plug-in could not allocate a resource. "null pointer encountered" The plug-in encountered a null pointer. Check detailed message. =============== Troubleshooting =============== 1. Server Error (0x80070005) - Access is denied. Cause: If the user who starts Windows Media Services does not have access privileges to access the Plug-in DLL files, this error appears when you try to enable the Plug-in Action: Add the user account to the group of user names that have permission to access the directory that contains the Plug-in DLL files. 2. Cannot stream media from the publishing point configured with Oracle Multimedia Custom DataSource Plug-in. Cause: If a fatal error occurs, Windows Media Server will automatically disable the Plug-in. Action: Check the Server Properties tab to see if the Plug-in is enabled. If the Plug-in is disabled, fix the problem based on the error message shown in server Troubleshooting pane. Enable the Plug-in before streaming is restarted.