IBM VideoCharger Player Version 2.0
Software Developer's Kit

Notices

Trademarks

Introduction to the IBM VideoCharger Player SDK

API Language Reference

Steps to Use the API in a Visual Basic Application

Steps to Use the API in a Visual J++ Application

Steps to Use the API in a Visual C++ Application

Visual C++ and Visual Basic Code Samples

Before using this document, read the general information under "Notices".

First Edition, July 1999

This edition applies to Version 2.0 of the IBM VideoCharger Player Software Developer's Kit and to all subsequent releases and modifications until otherwise indicated in new editions or technical newsletters.

(c) Copyright International Business Machines Corporation 1999. All rights reserved.

Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation
IBM Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation
Department W92/H3
555 Bailey Avenue
P.O. Box 49023
San Jose, CA 95161-9023
U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.

Trademarks

 

The following terms are trademarks of International Business Machines Corporation in the United States or other countries or both:

Java is a trademark of Sun Microsystems, Inc. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other countries.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States and/or other countries.

Other company, product, and service names may be trademarks or service marks of others.

Introduction to the VideoCharger Player SDK

The VideoCharger Player provides a high level API based on the ActiveX component specification for the Windows 95/98/NT environment. It enables custom Windows applications to access streaming video and audio from a VideoCharger Server. The API defines the basic control operations for playing media such as play, pause, stop and seek. Applications can integrate the video window provided by the player API into its application without detail knowledge of the internal operations of the VideoCharger Server.

Installing the Player SDK

  1. You must already have installed the VideoCharger Player on your PC.
  2. Unzip iscsdk.zip in the existing "IBM VideoCharger Player" directory.

The Player SDK consists of online help, the API DLL, associated source files, and sample programs:

Users not familiar with the ActiveX Component Object Model (COM) should consult the Microsoft Visual C++ or Visual Basic online help.

The VideoCharger Player API Language Reference

The Player API currently supports the operations of the IBM VideoCharger Player application and the associated VideoCharger web browser plugin by providing the video display window and control operation. These two applications define the initial API requirements and share the common services of the Player API. The API consists of methods for initialization/cleanup, metadata file interface, window control, VCR control, and advanced GUI functions.

The methods are listed alphabetically in this section. As you will notice, each method is declared as a C++ method (STDMETHOD), followed by a Visual Basic subroutine (Sub), followed by a J++ method.

STDMETHOD Cleanup ();
Sub Cleanup()
void Cleanup();

STDMETHOD CreateInfoPanel( OAHWND hOleWnd);
Sub CreateInfoPanel(hOleWnd As Long)
void CreateInfoPanel( long hOleWnd);

STDMETHOD DeleteMetaFile();
Sub DeleteMetaFile()
void DeleteMetaFile();

STDMETHOD DisplayStatistics(OAHWND hOleWnd);
Sub DisplayStatistics(hOAWnd As Long)
void DisplayStatistics(long hOAWnd);

STDMETHOD Forward();
Sub Forward()
void Forward();

STDMETHOD FullScreen();
Sub FullScreen()
void FullScreen();

STDMETHOD GetCurrentPlayPosition(double *pos);
Sub GetCurrentPlayPosition(pos As Double)
void GetCurrentPlayPosition(double* pos);

STDMETHOD GetMovieName(BSTR *bsName);
Sub GetMovieName(bsName As String)
void GetMovieName(BSTR* bsName);

STDMETHOD GetPlayDuration(double *duration);
Sub GetPlayDuration(duration As Double)
void GetPlayDuration(double* duration);

STDMETHOD GetPlayingState(short *nPlayingState);
Sub GetPlayingState(nPlayingState As Integer)
void GetPlayingState(short* nPlayingState);

STDMETHOD GetInvalidCommands(ulong *restrictions);
Sub GetInvalidCommands(restrictions As UnknownType)
void GetInvalidCommands(unsigned long* restrictions);

STDMETHOD GetPlayRange(double* pStart, double* pStop);
Sub GetPlayRange(pStart As Double, pStop As Double)
void GetPlayRange(double* pStart, double* pStop);

STDMETHOD GetVideoSize(short *width, short *height);
Sub GetVideoSize(width As Integer, height As Integer)
void GetVideoSize(short* width, short* height);

STDMETHOD Initialize ( OAHWND hOleWnd, BOOL bNPlugIn, short nPlayType);
Sub Initialize(hOleWnd As Long, bNPlugIn As Long, nPlayType As Integer)
void Initialize ( long hOleWnd, long bNPlugIn, short nPlayType);

STDMETHOD InitRegData(BOOL bInitData);
Sub InitRegData(bInitData As Long)
void InitRegData(long bInitData);

STDMETHOD IsMulticast(BOOL *bMulticast);
Sub IsMultiCast(bMultiCast As Long)
void IsMulticast(long* bMulticast);

STDMETHOD Mute();
Sub Mute()
void Mute();

STDMETHOD NewClip ( OAHWND hOleWnd, UINT nPlayType);
Sub NewClip(hOleWnd As Long, nPlayType As Integer)
void NewClip ( long hOleWnd, short nPlayType);

STDMETHOD Pause();
Sub Pause()
void Pause();

STDMETHOD Play();
Sub Play()
void Play();

STDMETHOD ResetInfoPanel();
Sub ResetInfoPanel()
void ResetInfoPanel();

STDMETHOD Rewind();
Sub Rewind()
void Rewind();

STDMETHOD SetAutoRepeat(BOOL bRepeat);
Sub SetAutoRepeat(bRepeat As Long)
void SetAutoRepeat(long bRepeat);

STDMETHOD SetAutoRewind(BOOL rewind);
Sub SetAutoRewind(rewind As BOOL)
void SetAutoRewind(long rewind);

STDMETHOD SetConfiguration (short left, short right, short top, short bottom);
Sub SetConfiguration(left As Integer, right As Integer, top As Integer, bottom As Integer)
void SetConfiguration (short left, short right, short top, short bottom);

STDMETHOD SetInfoPanelPos( OAHWND hOleWnd, short x, short y, short width, short height, BOOL bBottomLine);
Sub SetInfoPanelPos(hOleWnd As Long, x As Integer, y As Integer, width As Integer, height As Integer, bBottomLine As Long)
void SetInfoPanelPos( long hOleWnd, short x, short y, short width, short height, long bBottomLine);

STDMETHOD SetMetaData( BSTR szFile, short* pMetaError);
Sub SetMetaData(szFile As String, pMetaError As Integer)
void SetMetaData( BSTR szFile, short* pMetaError);

STDMETHOD SetPlayState(short *nPlayingState);
Sub SetPlayState(nPlayState As Integer)
void SetPlayState(short nPlayState);

STDMETHOD SetTabBegin(short t_step);
Sub SetTabBegin(t_step As Integer)
void SetTabBegin(short t_step);

STDMETHOD SetTabEnd(short t_step);
Sub SetTabEnd(t_step As Integer)
void SetTabEnd(short t_step);

STDMETHOD SetVolume(long volume);
Sub SetVolume(volume As Long)
void SetVolume(long volume);

STDMETHOD SetWindowPos ( OAHWND hOleWnd, short x, short y, short width, short height);
Sub SetWindowPos(hOleWnd As Long, x As Integer, y As Integer, width As Integer, height As Integer)
void SetWindowPos ( long hOleWnd, short x, short y, short width, short height);

STDMETHOD ShowInfoPanel(BOOL bShow)
Sub ShowInfoPanel(bShow As Long)
void ShowInfoPanel(long bShow)

STDMETHOD StepBackward (long btime);
Sub StepBackward(btime As Double)
void StepBackward (double btime);

STDMETHOD StepForward(long ftime);
Sub StepForward(ftime As Double)
void StepForward(double ftime);

STDMETHOD Stop();
Sub Stop()
void Stop();

STDMETHOD StopSeekPause( double position);
Sub StopSeekPause(position As Double)
void StopSeekPause( double position);

STDMETHOD TraceSetup (OAHWND hOleWnd);
Sub TraceSetup(hOAWnd As Long)
void TraceSetup (long hOAWnd);

STDMETHOD UpdatePlayEvent();
Sub UpdatePlayEvent()
void UpdatePlayEvent();

Steps to Use the SDK in a Visual Basic Application

These are the steps for creating a new Visual Basic application which uses the VideoCharger SDK to play audio/video files. The steps assume you are using Microsoft Visual Basic 6.0 development environment. You must already have IBM VideoCharger Player installed on your machine.

The instructions assume you have a working knowledge of Windows GUI programming. As a starting point, you can use the Code Samples for reference.

  1. Create a new application with Visual Basic:
  2. View the MPlayerLib in the Object Viewer:
  3. Add code to create an ISCMPlayer object:
  4. Call ISCMPlayer methods:
  5. Create a Timer object for an interval of less than 500 milliseconds. Call player.UpdatePlayEvent() to update video and network status.

Steps to Use the SDK in a Visual J++ Application

These are the steps for creating a new Visual J++ application which uses the VideoCharger SDK to play audio/video files. The steps assume you are using Microsoft Visual J++ 6.0 development environment. You must have IBM VideoCharger Player installed on your machine.

The instructions assume you have a working knowledge of Windows GUI programming. As a starting point, you can use the Code Samples for reference.

  1. Copy IISCMPlayer.java and ISCMPlayer.java into winnt\java\TrustLib\mplayer directory.
  2. Create a new application with Visual J++:
  3. Call ISCMPlayer methods:
  4. Create a Timer object for an interval of less than 500 milliseconds. Call mplayer.UpdatePlayEvent() to update video and network status.

Steps to Use the SDK in a Visual C++ Application

These are the steps for creating a new Visual C++ application which uses the VideoCharger SDK to play audio/video files. The steps assume you are using Microsoft Visual C++ 5.0 development environment. You must have IBM VideoCharger Player installed on your machine.

The instructions assume you have a working knowledge of Windows C++ GUI programming. As a starting point, you can use the Code Samples for reference.

The client application is a single document interface Win32 application whose purpose is to call functions in the Mplayer COM.

  1. Create a new application with Visual C++:
  2. Copy the following files from \sdk\Src\ to the current project directory. These are external dependencies that will automatically be added to your project:
  3. Make modifications to the generated files to reference the ISCMPlayer COM object.

    stdafx.h: Note: You can copy stdafx.h from the \sdk\Src\ directory to the current project directory to replace the default file. The changes specified here have already been made.

    To add the Mplayer COM in vcPlayer's path, open stdafx.h and add the following lines immediately after the MFC include #include < afxdisp.h>:
    #import "MPlayer.tlb"
    #include "MPlayer_i.c"

    vcPlayer.h: Declare the mplayer namespace in the vcPlayer file. MPLAYERLib is defined in mplayer_i.c. Open the file vcPlayer.h and add the following line after the #include resource.h declaration:
    using namespace MPLAYERLib;

    vcPlayer.cpp: Declare the mplayer namespace in the CPP file. Add the following line after the #define statements:
    using namespace MPLAYERLib;

    Create a member variable that will hold a pointer to an interface in MPlayer's COM object. We use IISCMPlayer as the template type, since that is the name of the interface that will be created. IISCMPlayer is declared in MPlayer_i.c, which is included in stdafx.h. After declaring theApp object (CVcPlayerApp theApp;), add the following line:
    IISCMPlayerPtr p_ISCMPlayer;

    Mainfrm.h: Declare the mplayer namespace in the main frame CPP file where we will be making our mplayer calls. Add the following line at the top of the file, before the class statement:
    using namespace MPLAYERLib;

    Mainfrm.cpp: Declare the mplayer pointer in the main frame file to use the COM object. Verify the iscplaysdk.h is in the current project directory. Add the following lines immediately after the include statements:
    #include "iscplaysdk.h"
    extern IISCMPlayerPtr pISCMPlayer;

  4. Call ISCMPlayer methods:
  5. In OnInitDialog(), SetTimer() for an interval of less than 500 milliseconds. In the corresponding OnTimer() message Handler, call pISCMPLayer->UpdatePlayer() to update video and network status.

    Explore the Samples for the VideoCharger Player SDK

    The sample applications are located in the directories found at the following location:

    sdk\Samples\

    The following list shows the sample programs written in Visual Basic, Visual C++, and Visual J++ to use the VideoCharger SDK to create streaming media players.

    Appendix - Metadata File Structure

    The Metadata file contains pertinent information regarding the session and the video stream. This information is created by the VideoCharger Server. A description of the fields within the metadata file follows.

    Session Data

    The following information is related to the session that is established between the VideoCharger Client and the Server.

    Stream Data

    The following information is related to the stream to be viewed.

    Metadata File Format

    The file format is a collection of "stanzas". Each stanza is delimited by a starting and ending keyword enclosed in brackets. Within the bracketed section are keyword/value pairs.

    All values are character which should be converted to ulong when received by the client except serveraddr, title, and longname which should remain character strings.


    ************************ Begin metadata file ************************
    Content_type: video/x-ibm-ivs
    [ivs_session_begin]
    version=
    passticket=
    protocol=
    serveraddr=
    codepage=
    numberstreams=
    sessiontype=
    dataprotocol=
    sourceaddr=
    [ivs_session_end]
    [ivs_stream_begin]
    title=
    longname=
    length=
    mediatype=
    bitrate=
    autoplay=
    invalidcommands=
    filesize64=
    [ivs_stream_end]
    ***************************** End of metadata file ************************