The Microsoft NetShow SDK

The Microsoft NetShow Beta SDK

[This is preliminary documentation and subject to change.]

This SDK provides procedural and reference information for the functionality exposed to developers and Web administrators by the Microsoft®NetShow™ platform. This documentation, along with the samples, is designed to facilitate development of applications built on top of the NetShow platform. With this beta SDK, you can create applications that interact with the various NetShow services and components to perform an assortment of tasks, including the following:

  • Building custom user interfaces for Netshow components.

  • Building companion applications that work in concert with NetShow services and applications.

  • Integrating NetShow components with Web site management applications.

  • Adding NetShow multimedia streaming capabilities to Web pages.

NetShow Overview

Microsoft NetShow is a powerful solution for streaming multimedia content across corporate intranets and the Internet. It enables development of Web sites or Web applications that stream audio, video, and script commands as a continuous flow of data. The ability to stream multimedia means the client can render content as it is being received over the network without downloading it first. Streaming is superior to downloading multimedia files because it greatly reduces the wait time and storage requirements on the client computer. Streaming also opens the door to unlimited length presentations, as well as live broadcasts.

NetShow content is based on the open, standards-based Advanced Streaming Format (ASF). ASF is an open standard that supports data delivery over a wide variety of networks and protocols. ASF describes a transmission file format (as opposed to a wire format) for arranging and organizing synchronized multimedia data. It is optimized for streaming the data over networks and rendering the data on a client computer. ASF specifies the format of live presentations being streamed across the network as well as pre-recorded .asf files.

NetShow supports unicasting (sending a stream to each client requesting it) and multicasting (sending a single stream across the network that can be rendered by many clients at the same time). Unicasting allows the user to start, stop, pause, fast forward, or rewind the stream at will. However sending a stream to each individual client can require a lot of bandwidth. Multicasting, on the other hand, makes better use of available bandwidth. Much like tuning into a TV or radio broadcast, multicasting restricts the users ability to pause, rewind, or fast forward the presentation.

© 1996-1998 Microsoft Corporation. All rights reserved.


About the NetShow SDK

About the NetShow Beta SDK

The NetShow SDK encompasses a wide variety of technologies. Some sections of this documentation are structured to meet the needs of Web authors wishing to add streaming media to their Web sites. Other sections are geared toward ISVs developing Web-based software solutions.

This documentation is divided into based on the corresponding system components. The NetShow SDK is comprised of the following components:

Component | Description
NetShow Unicast Manager Control | A Microsoft ActiveX® control that exposes attributes for configuring, monitoring, and managing NetShow unicasting services.
NetShow Authentication API | A COM-compliant API for developing packages that authenticate users before allowing them access to NetShow content.
NetShow Event Notification and Authorization API | A COM-compliant API for developing packages that require the server to obtain authorization before performing tasks and to send notification when the task is complete.
NetShow Station Manager Control | An ActiveX control that exposes attributes for configuring, monitoring, and managing NetShow multicasting services.
NetShow File Transfer Control | An ActiveX control used to receive multicast file transfers.
NetShow Encoder | An Automation object that exposes the functionality used to create ASF streams.

The documentation for each component is divided into four sections:

  • The About section describing the architecture of the control or API.

  • The Using section describing ways to implement the control or API.

  • The Reference section with complete descriptions of each interface, method, property, event, or structure exposed by the control or API.

  • The Sample section, containing a description of each sample, along with pointers or links to sample code and/or scripts that demonstrates using the control or API.


New Features for Version 3.0

This section to be completed post-beta.


The NetShow Programming Model

NetShow is an open-standards-based platform that exposes functionality to developers through a variety of techniques. These include:

  • The Component Object Model (COM) - The standard for building reliable, interoperable software components. COM is programming-language independent; however, this SDK concentrates on COM components (objects) implemented through Microsoft Visual C++® base classes.

  • Automation (formerly called OLE Automation) - A software technology that implements it’s features primarily through the COM IDispatch interface. Exposing methods, properties, and events through Automation is supported by a host of programming environments, including Microsoft Visual Basic®, Visual C++, and Java applications.

  • ActiveX controls - Fully compiled, self-contained software components that are ideal for Web development. ActiveX controls can be used to develop Visual Basic, Visual C++, and Java applications, or they can be inserted into HTML pages for Web-based applications. ActiveX controls are easy to manipulate using scripting languages such as Microsoft Visual Basic Scripting Edition (VBScript) or Java Script (JScript).

Different NetShow components expose their functionality through different technologies. The following table shows the relationship between the NetShow components and their underlying technology:

NetShow Components | Programming Technology
NetShow Unicast Manager Control NetShow Multicast Station Manager Control NetShow File Transfer Control | ActiveX
NetShow Encoder | Automation
Event Notification and Authorization API Authentication API | COM


Document Conventions

This SDK uses the following document conventions:

Convention | Description
Monospace
 Indicates syntax or code examples
Bold | Indicates a function, structure, interface, method, event, property, or object name.
Italic | Indicates placeholders, most often as attribute parameter names. Placeholders represent information that must be supplied by the implementer.
[ ] Indicates optional syntax items. Type in only the information between the brackets, not the brackets themselves.


NetShow Unicast Manager Controls Programming Guide

[This is preliminary documentation and subject to change.]

Microsoft® NetShow™ Unicast Manager, packaged in the Nsunimgr.ocx file, embodies two Microsoft ActiveX® controls: NetShow Unicast Manager Admin and NetShow Unicast TraceView. The Admin control also manages various objects. This portion of the Microsoft NetShow SDK document describes the functionality exposed by these controls for creating custom administration, monitoring applications, and integrating NetShow into other software products. The document strives to lay a conceptual foundation and to provide practical guidelines for programming with the NetShow Unicast Manager controls. The discussion is divided into the following topics:

Topic | Description
About the Netshow Unicast Manager Admin Control | Introduces the architecture and utility of the NetShow Unicast Manager Admin control.
Using the Netshow Unicast Manager Admin Control | Presents a guideline to using the NetShow Unicast Manager Admin control in your applications.
Reference of the Netshow Unicast Manager Admin Control | Presents API references of the NetShow Unicast Manager Admin control, including events, methods, properties, and objects.
About the NetShow Unicast TraceView Control | Introduces the architecture and utility of the NetShow Unicast TraceView control.
Using the NetShow Unicast TraceView Control | Presents a guideline to using the NetShow Unicast TraceView control in your application.
Reference of the NetShow Unicast TraceView Control | Presents API references of the NetShow Unicast TraceView control, including events, methods, and properties.
Samples of using the NetShow Manager Admin and TraceView controls | Sample applications that illustrate how to use the Admin and TraceView controls in HTML, VBScript, and C/C++.

The NetShow Unicast Manager controls require that Nsunimgr.ocx and Nsoobj.dll be present and registered on the computer.


About the Netshow Unicast Manager Admin Control

The NetShow Unicast Manager Admin control is an ActiveX control used to administer a NetShow unicast server. It manages a set of objects for providing various services. For example, the Client object represents a client connected to the NetShow server and the Clients object represents a collection of the Client objects. The AuthenticationPlugin object authenticates clients for the server.

At present, the NetShow Unicast Server can only run on computers running Microsoft Windows NT® Workstation or Microsoft Windows NT Server version 4.0 operating systems. However, the NetShow Unicast Manager admin control can run on computers running either Microsoft Windows NT 4.0 or Microsoft Windows® 95. For more information about NetShow, visit the NetShow home page at http://www.microsoft.com/netshow/.


Using the NetShow Unicast Manager Admin Control

The NetShow Unicast Manager SDK setup program installs and registers the NetShow Unicast Manager controls and related files. The control can be added to any Microsoft Visual Basic® or Visual C++® application like any other ActiveX control.

With the Unicast Manager Admin control, you can leverage the well-tested functionality for managing NetShow unicast services, which include:

  • Setting and retrieving server properties, such as the maximum aggregate bandwidth and the maximum number of clients.
  • Monitoring client behavior, including connections, disconnections, and titles played.
  • Monitoring overall system activity, including server status, administration functions, and server limits.
  • Filtering the types of events received by the control.

The properties exposed by the NetShow Manager Admin control are run time properties; that is, they are not available at design time. The values of these properties can not be set or returned until the Connect method has completed successfully.

As with any other ActiveX control, you can use the NetShow Unicast Manager Admin control directly in HTML pages (with or without Visual Basic Scripting) and in Visual Basic or Visual C++ applications. There are several convenient ways to embed ActiveX controls in HTML pages. You can use the ActiveX Control Pad, Microsoft Visual InterDev, or Microsoft FrontPage™. For more information on using ActiveX controls, see the Microsoft Web pages at http://www.microsoft.com/activex. You can also find additional information and resources listed in the “More Information and Examples” section of the NetShow Player Software Developer's Kit.


Reference of the NetShow Unicast Manager Admin Control

This section lists the events, methods, and properties supported by the NetShow Unicast Manager Admin control.

Besides being an object itself, the NetShow Unicast Manager Admin control also manages several other objects, each of which may have its own methods or properties.


Unicast Manager Admin Control Events

NetShow Unicast Manager Admin control events are divided into the following categories:

  • Server Events - Events dealing with the unicast server.
  • Administration Events - Events fired when administration properties are set by any administrator.
  • Client Events - Events fired by clients receiving a unicast.
  • Alert Events - Events fired when imposed limits are reached.

The HRESULT parameters for this control are listed in the Nserror.h file.

The following events are supported by the NetShow Unicast Manager control:

Server Events | Fired When
OnEventBacklogReached | A remote monitor has too many events in the queue.
OnServerFault * | A server fault occurs.
OnServerOffline | The server goes offline.
OnServerOnline | The server goes online.
Administration Events | Fired When
OnAdminBandwidthLimit | The aggregate bandwidth limit is changed.
OnAdminClientLimit | The client limit is changed.
OnAdminFileBitRateLimit | The file bit-rate limit is changed.
OnAdminKillClient | A client is disconnected by a call to the KillClient method
OnAdminSecurityEnabled | Security is enabled or disabled.
Client Events | Fired When
OnClientConnect | A client connects.
OnClientDisconnect | A client disconnects.
OnClientPlay | A client starts to play a title.
OnClientStop | A client stops playing a title.
OnClientStride | A client begins to scan a file (fast forward or fast reverse).
Alert Events | Fired When
OnMaxBandwidth | The aggregate bandwidth limit is reached.
OnMaxClients | The client limit is reached.
OnMaxFileBitRate | The file bit-rate limit is reached.

Events marked with an asterix (*) are new in NetShow version 3.0.


OnAdminBandwidthLimit

OnAdminBandwidthLimit Event

Indicates that the aggregate bandwidth limit was changed.

Syntax

NSUnicastMgr_OnAdminBandwidthLimit( datetime, status, ipaddress, maxBandWidth, VirtualPath)

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich mean time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired. A value of S_OK (0) indicates success.

ipaddress

A String value specifying the administrator's IP address. If the connection is to LocalHost, this value will be 0.0.0.0, and the connection will be made to the computer on which the script is running.

maxBandWidth

A Long value specifying the new bit-rate limit in bits per second.

VirtualPath

A String value specifying the alias of the virtual root that caused the limit to be exceeded. A NULL value (or empty string in Visual Basic) indicates a system-wide limit has been exceeded.

Remarks

This event is called whenever an administrative client sets the MaxBandwidth property. To receive notification of this event, the AdminEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnAdminBandwidthLimit( time, status, ip, mbw, vp )
  MsgBox( "set by " & ip & " to " & mbw & "bps" )
End Sub
 ' event on next line opens message box
NSUnicastMgr1.MaxBandwidth = 123456

See Also

MaxBandwidth, OnMaxBandwidth


OnAdminClientLimit

OnAdminClientLimit Event

Indicates the client limit was changed.

Syntax

NSUniMgr_OnAdminClientLimit( datetime, status, ipaddress, count, VirtualPath )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired.

ipaddress

A String value specifying the administrator's IP address.

count

A Long value specifying the new client limit.

VirtualPath

A String value specifying the alias of the virtual root that caused the limit to be exceeded. A NULL value (or empty string in Visual Basic) indicates a system-wide limit has been exceeded.

Remarks

This event is called whenever an administrative client sets the MaxClients property. To receive notification of this event, the AdminEvents property must first be set to TRUE.

Example

In this example, the event handler for the OnAdminClientLimit event brings up a message box when the MaxClients property is changed. The message box shows the IP address of the administrative client making the change. (In this case, the IP of the computer running the example.) The last line in this sample causes the event to be fired.

Sub NSUnicastMgr_OnAdminClientLimit( time, hr, ip, count, vp)
 MsgBox( "computer at ip " & ip & " changed MaxClients to " & count)
End Sub
 ' event on next line opens message box
NSUnicastMgr.MaxClients = 200

See Also

MaxClients


OnAdminFileBitRateLimit

OnAdminFileBitRateLimit Event

Indicates the file bit-rate limit was changed.

Syntax

NSUnicastMgr_OnAdminFileBitRateLimit( datetime, status, ipaddress, maxFileBitRate )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired.

ipaddress

A String value specifying the administrator's IP address.

maxFileBitRate

A Long value specifying the new file bit-rate limit in bits-per-second.

Remarks

This event is called whenever an administrative client sets the MaxFileBitRate property. To receive notification of this event, the AdminEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnAdminFileBitRateLimit( time, hr, ip, rate )
  MsgBox( "maximum file bit rate is" & rate )
End Sub
 ' event on next line opens message box
NSUnicastMgr1.MaxBandwidth = 3000

See Also

MaxFileBitRate, OnMaxFileBitRate


OnAdminKillClient

OnAdminKillClient Event

This event is fired when a client is disconnected by an administrator.

Syntax

NSUnicastMgr_OnAdminKillClient( datetime, status, ipaddress, clientID )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired.

ipaddress

A String value specifying the administrator's IP address. If the connection is to LocalHost, this value will be 0.0.0.0, and the connection will be made to the computer on which the script is running.

clientID

A Long value specifying the ID of the client that was disconnected.


OnAdminSecurityEnabled

OnAdminSecurityEnabled Event

Indicates security was enabled or disabled.

Syntax

NSUnicastMgr_OnAdminSecurityEnabled( datetime, status, ipaddress, fEnabled )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired.

ipaddress

A String value specifying the administrator's IP address.

fEnabled

A Boolean value specifying the security state. True if security was enabled, False if not.

Remarks

This event is called whenever a client enables or disables security on a NetShow unicast server. To receive notification of this event, the AdminEvents property must be set to TRUE (the default value).

See Also

AdminEvents


OnClientConnect

OnClientConnect Event

Indicates a client connected.

Syntax

NSUnicastMgr_OnClientConnect( datetime, status, clientid, ipaddress, port )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired.

clientid

A Long value specifying the client ID.

ipaddress

A String containing the client's IP address.

port

An Integer specifying the TCP port used by the client.

Remarks

This event is called whenever a client connects. It does not indicate play activity. To receive notification of this event, the ClientEvents property must be set to TRUE (the default value).

Example

Sub NSUnicastMgr_OnClientConnect( datetime, status, clientid, ip, port )
   MsgBox( "client at " & ip " connected )
End Sub

See Also

OnClientDisconnect, OnClientPlay, OnClientStop, OnClientStride


OnClientDisconnect

OnClientDisconnect Event

Indicates that a client disconnected.

Syntax

NSUnicastMgr_OnClientDisconnect( datetime, status, clientid, ipaddress, port )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired.

clientid

A Long value specifying the client ID.

ipaddress

A String containing the client's IP address.

port

An Integer specifying the TCP port used by the client.

Remarks

This event is called whenever a client (using the NetShow Player or client control) disconnects. To receive notification of this event, the ClientEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnClientDisconnect(datetime, status, clientid, ip, port)
  ' message box opens when a client disconnects
  MsgBox( "client at " & ip " disconnected )
End Sub

See Also

OnClientConnect, OnClientPlay, OnClientStop, OnClientStride


OnClientPlay

OnClientPlay Event

Indicates a client started to play a title.

Syntax

NSUnicastMgr_OnClientPlay( datetime, status, clientid, filename )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired.

clientid

A Long value specifying the client ID.

filename

A String containing the name of the title the client is playing.

Remarks

This event is called whenever a client (using the NetShow Player or client control) plays a file. To receive notification of this event, the ClientEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnClientPlay(datetime, status, clientid, filename)
  MsgBox( "client " & clientid " playing " & filename )
End Sub
' MediaPlayer object on next line is instance of Microsoft Media Player
MediaPlayer.FileName = "mms://LocalHost/sample.asf"
' event at next line opens message box
MediaPlayer.Play

See Also

OnClientConnect, OnClientDisconnect, OnClientStop, OnClientStride


OnClientStop

OnClientStop Event

Indicates a client stopped playing a file.

Syntax

NSUnicastMgr_OnClientStop( datetime, status, clientid, filename )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired.

clientid

A Long value specifying the client ID.

filename

A String containing the name of the title the client stopped playing.

Remarks

This event is called whenever a client (using the NetShow Player or Client control) stops playing a title. To receive notification of this event, the ClientEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnClientStop(datetime, status, clientid, filename)
  MsgBox( "client " & clientid " stopped playing " & filename )
End Sub
' MediaPlayer object on next line is instance of Microsoft Media Player
MediaPlayer.FileName = "mms://LocalHost/sample.asf"
MediaPlayer.Play
' event at next line opens message box
MediaPlayer.Stop

See Also

OnClientConnect, OnClientDisconnect, OnClientPlay, OnClientStride


OnClientStride

OnClientStride Event

Indicates a client began scanning a file (fast forward or fast reverse).

Syntax

NSUnicastMgr_OnClientStride( datetime, status, clientid, filename )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back when this event is fired.

clientid

A Long value specifying the client ID.

filename

A String containing the name of the title the client is scanning.

Remarks

This event is called whenever a client (using the NetShow Player or client control) begins scanning a title. To receive notification of this event, the ClientEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnClientStride(datetime, status, clientid, filename)
  ' message box opens if a client begins scanning
  MsgBox( "client " & clientid " scanning through " & filename )
End Sub

See Also

OnClientConnect, OnClientDisconnect, OnClientPlay, OnClientStop


OnEventBacklogReached

OnEventBacklogReached Event

Indicates that the application has fallen too far behind and has been disconnected.

Syntax

NSUnicastMgr_OnEventBacklogReached( datetime )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

Remarks

This event is fired when the instance of the server running the administration page cannot keep up with the events being fired on the server, causing the advise sink connection to be disconnected.

To receive notification of this event, the ServerEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnEventBacklogReached( datetime)
  MsgBox( "server disconnecting due to event backlog at " & datetime)
End Sub

See Also

AdminEvents


OnMaxBandwidth

OnMaxBandwidth Event

Indicates the aggregate bandwidth limit was reached.

Syntax

NSUnicastMgr_OnMaxBandwidth( datetime, rate, VirtualPath )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

rate

A Long value specifying the current aggregate bandwidth limit.

VirtualPath

A String value specifying the alias of the virtual root that caused the limit to be exceeded. A NULL value indicates a system-wide limit has been exceeded.

Remarks

This event is called the sum of all client bandwidth use exceeds the amount specified by the MaxBandwidth property. To receive notification of this event, the AlertEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnMaxBandwidth(datetime, rate, vp)
  ' message box opens if bandwidth limit is exceeded
  MsgBox( "maximum bandwidth of " & rate & " exceeded at " & datetime )
End Sub

See Also

MaxBandwidth, MaxFileBitRate, OnMaxFileBitRate


OnMaxClients

OnMaxClients Event

Indicates the limit to the maximum number of simultaneously connected clients was reached.

Syntax

NSUnicastMgr_OnMaxClients( datetime, count, VirtualPath )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

count

A Long value specifying the current number of clients.

VirtualPath

A String value specifying the alias of the virtual root that caused the limit to be exceeded. A NULL value indicates a system-wide limit has been exceeded.

Remarks

This event is called the total number of connected clients exceeds the amount specified by the MaxClients property. To receive notification of this event, the AlertEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnMaxClients(datetime, count, vp)
   ' message box opens if client limit is exceeded
   MsgBox( count & " clients exceeded limit at " & datetime )
End Sub

See Also

MaxClients


OnMaxFileBitRate

OnMaxFileBitRate Event

Indicates the file bit-rate limit was reached.

Syntax

NSUnicastMgr_OnMaxFileBitRate( datetime, rate )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

rate

A Long value specifying the current file bit-rate limit.

Remarks

This event is called when a client uses bandwidth in excess of the amount specified by the MaxFileBitRate property. To receive notification of this event, the AlertEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnMaxFileBitRate( datetime rate )
  ' message box opens if bit rate limit is exceeded
  MsgBox( "a file playing at " & rate & " bps exceeded the limit" )
End Sub

See Also

MaxFileBitRate, MaxBandwidth, OnMaxBandwidth


OnServerFault

OnServerFault Event

This event is fired when a server fault occurs.

Syntax

NSUnicastMgr_OnServerFault( datetime, Status )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

Status

An HRESULT value indicating the type of fault that occurred.

See Also

OnServerOffline


OnServerOffline

OnServerOffline Event

Indicates the NetShow unicast server went offline.

Syntax

NSUnicastMgr_OnServerOffline( datetime, status )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT).

status

A Long value specifying the HRESULT passed back indicating why the server went offline.

Remarks

To receive notification of this event, the ServerEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnServerOffline(datetime, status)
  ' message box opens if the server goes offline
  MsgBox( "server went offline at " & datetime )
End Sub

See Also

OnServerOnline


OnServerOnline

Indicates the NetShow unicast server went online.

Syntax

NSUnicastMgr_OnServerOnline( datetime )

Parameters

datetime

A Date value indicating the time the event occurred, expressed in Greenwich Mean Time (GMT ).

Remarks

To receive notification of this event, the ServerEvents property must first be set to TRUE.

Example

Sub NSUnicastMgr_OnServerOnline( datetime)
  ' message box opens if the server comes online
  MsgBox( "server came online at " & datetime)
End Sub

See Also

OnServerOffline


Unicast Manager Admin Control Methods

The following methods are supported by the NetShow Unicast Manager Admin control.

Method | Description
Connect | Connects to a NetShow Unicast Manager server.
KillClient | Disconnects a client connected to this NetShow server.
SetProxyAuthenticationInfo | Sets HTTP proxy authentication credentials.


Connect

Connect Method

Makes a connection to a unicast server.

Syntax

NSUnicastMgr.Connect( ServerName )

Parameters

ServerName

A String specifying the name of the server.

Return Values

Returns an ActiveX HRESULT error code.

Remarks

Specifying LocalHost as ServerName makes a connection to the computer on which the script is running.

Example

The following VBScript indicates an attempt to establish a connection to a NetShow server running on the same computer. If the connection fails, it provides a description of the reason for the failure.

On Error Resume Next
NSUnicastMgr.Connect "LocalHost"
If Err.Number = 0 Then
 MsgBox "Connected"
Else
 MsgBox "Not Connected: " & Err.Description
End If


KillClient

KillClient Method

Disconnects a client from the NetShow server.

Syntax

NSUnicastMgr.KillClient( clientID )

Parameters

clientID

A Long value specifying the identifier of a client being disconnected.

Return Values

Returns an ActiveX HRESULT error code.

Remarks

This method is analogous to the Client.Disconnect method.

See Also

Client.Disconnect


SetProxyAuthenticationInfo

SetProxyAuthenticationInfo Method

Sets HTTP proxy authentication credentials.

Syntax

NSUnicastMgr.SetProxyAuthenticationInfo( bstrUser, bstrPasswd )

Parameters

bstrUser

A String value specifying the domain and user name. The domain is optional.

bstrPasswd

A String value specifying the password.

Return Values

Returns an ActiveX HRESULT error code.

Remarks

NetShow supports HTTP stream distribution among NetShow servers. For example, the server connected to this instance of the Unicast Manager Admin control could be distributing streams to multiple downstream servers. It may try, using HTTP, to connect to a server behind a firewall. This method is used to set the username and password credentials needed to break through the firewall if this server is challenged by a proxy server.

See Also

ProxyUser, ProxyHostName, EnableProxy


Unicast Manager Admin Control Properties

The Unicast Manager control supports the following properties.

Property | Read/Write | Description
AdminEvents | RW | Enables or disables receipt of administration events.
AlertEvents | RW | Enables or disables receipt of alert events.
AuthenticationPlugins* | R | Returns a collection of authentication plug-ins.
ClientEvents | RW | Enables or disables receipt of client events.
Clients | R | Obtains a collection of all active clients.
EnableHttpStreaming | RW | Enables or disables Http streaming on this NetShow server.
EnableLogging | RW | Enables or disables logging.
EnableProxy | RW | Returns or sets a value indicating whether the proxy server is enabled.
EventPlugins* | R | Returns a collection of event handler/authorization plug-ins.
EventsProxy | RW | Returns or sets the name of a proxy monitor.
LogFileDirectory | RW | Returns or sets the directory of a log file.
LogFilePeriod | RW | Returns or sets the period of time logged events will be kept.
LogFileSize | RW | Returns or sets the maximum size for a log file.
MaxBandwidth | RW | Returns or sets the maximum aggregate bandwidth for the server.
MaxClients | RW | Returns or sets the maximum number of client connections.
MaxFileBitRate | RW | Returns or sets the maximum bit rate per file.
ProxyHostName* | RW | Returns the proxy host name.
ProxyUser* | R | Returns the user ID used for proxy authentication.
Server | R | Returns the name of the server currently connected.
ServerEvents | RW | Enables or disables receipt of server events.
ServerStatus * | R | Returns a value specifying the current status of the server.
VirtualRoots | R | Obtains a collection of all virtual roots.

* New in NetShow version 3.0.


AdminEvents

AdminEvents Property

A Boolean value specifying whether administration events are enabled or disabled for this instance of the Netshow Unicast Manager Admin control.

Syntax

NSUnicastMgr.AdminEvents

Remarks

The default value for AdminEvents is True. Administrative events are OnAdminBandwidthLimit, OnAdminClientLimit, OnAdminFileBitRateLimit, and OnAdminSecurityEnabled.

Example

If NSUnicastMgr.AdminEvents = False Then
  MsgBox "Administrative events are disabled"
End If

See Also

OnAdminBandwidthLimit, OnAdminClientLimit, OnAdminFileBitRateLimit, OnAdminSecurityEnabled


AlertEvents

AlertEvents Property

A Boolean value specifying whether alert events are enabled or disabled for this instance of the Netshow Unicast Manager Admin control.

Syntax

NSUnicastMgr.AlertEvents

Remarks

The default value for AlertEvents is True. Alert events include OnMaxBandwidth, OnMaxClients, and OnMaxFileBitRate.

Example

If Not NSUnicastMgr.AlertEvents Then
  MsgBox "Alert events are disabled"
End If

See Also

OnMaxBandwidth, OnMaxClients, OnMaxFileBitRate


AuthenticationPlugins

AuthenticationPlugins Property

Returns the collection of authentication package objects.

Syntax

NSUnicastMgr.AuthenticationPlugins

See Also

AuthenticationPlugins Collection Object


ClientEvents

ClientEvents Property

A Boolean value specifying whether client events are enabled or disabled for this instance of the Netshow Unicast Manager Admin control.

Syntax

NSUnicastMgr.ClientEvents

Remarks

The default value for ClientEvents is True. Client events are OnClientConnect, OnClientDisconnect, OnClientPlay, OnClientStop, and OnClientStride.

Example

If NSUnicastMgr.ClientEvents = False Then
  MsgBox "Client events are disabled"
End If

See Also

OnClientConnect, OnClientDisconnect, OnClientPlay, OnClientStop, OnClientStride


Clients

Clients Property

Obtains a snapshot collection object of all active clients.

Syntax

NSUnicastMgr.Clients


EnableHttpStreaming

EnableHttpStreaming Property

Returns or sets a Boolean value specifying whether the NetShow Unicast Manager Admin control will enable Http streaming. By default, this value is TRUE.

Syntax

NSUnicastMgr.EnableHttpStreaming

Example

Sub ToggleHttpStreaming
  ' Turns Http streaming on or off
   If NSUnicastMgr.EnableHttpStreaming = True Then
      NSUnicastMgr.EnableHttpStreaming = False
   Else
      NSUnicastMgr.EnableHttpStreaming = True
   End If
   MsgBox( "HttpStreaming value: " & NSUnicastMgr.EnableHttpStreaming)
End Sub


EnableLogging

EnableLogging Property

Returns or sets a Boolean value specifying whether the NetShow Unicast Manager Admin control will log activity. By default, this value is TRUE.

Syntax

NSUnicastMgr.EnableLogging

Example

Sub ToggleLogging
   ' Turns logging on or off
   If NSUnicastMgr.EnableLogging = True Then
      NSUnicastMgr.EnableLogging = False
   Else
      NSUnicastMgr.EnableLogging = True
   End If
   MsgBox( "Logging value: " & NSUnicastMgr.EnableLogging)
End Sub


EnableProxy

EnableProxy Property

Returns or sets a Boolean value indicating whether connecting to a proxy server is enabled.

Syntax

NSUnicastMgr.EnableProxy

Remarks

NetShow supports HTTP stream distribution among NetShow servers. For example, the server connected to this instance of the Unicast Manager Admin control could be distributing streams to multiple downstream servers. It may try, using HTTP, to connect to a server behind a firewall. This property is used to set or return a value that determines whether or not this server can connect to a proxy server.

See Also

ProxyUser, SetProxyAuthenticationInfo, ProxyHostName


EventPlugins

EventPlugins Property

Returns the collection of event notification and authorization plug-in objects.

Syntax

NSUnicastMgr.EventPlugins

See Also

EventPlugins Collection Object


EventsProxy

EventsProxy Property

Returns or sets a String value specifying the name of the proxy server monitoring the NetShow unicast server.

Syntax

NSUnicastMgr.EventsProxy

Remarks

The Unicast Manager Service and the NetShow Monitor Service compete with each other for system resources, particularly CPU time. The Unicast Manager Service gets priority over the NetShow Monitor Service. Under extremely heavy loads, monitoring may be discontinued. To relieve this conflict and ensure that the control receives all of its events, the NetShow Monitor Service can be set up to run from a remote computer, or "proxy monitor."

By default, the event proxy is the same computer as the server.

Example

MsgBox NSUnicastMgr.EventsProxy       ' show current proxy
NSUnicastMgr.EventsProxy = "NSPROXY"  ' connect to proxy server NSPROXY


LogFileDirectory

LogFileDirectory Property

Description

Returns or sets a String value specifying the target directory for the NetShow Unicast Manager event log.

Syntax

NSUnicastMgr.LogFileDirectory


LogFilePeriod

LogFilePeriod Property

Description

Returns or sets a Long value specifying the log-file period for this NetShow Unicast Manager Admin control.

Syntax

NSUnicastMgr.LogFilePeriod

Remarks

The log file period is a number whose value determines when the log file will be reset. Following is a list of supported values:

Value | Period | Description
0 | File size | The log file is reset when it reaches a specific size. This size is set or returned by using the LogFileSize property.
1 | Daily | The log file is reset daily.
2 | Weekly | The log file is reset weekly.
3 | Monthly | The log file is reset monthly.

To use the LogFileSize property, the value of the LogFilePeriod property must be zero.

See Also

LogFileSize


LogFileSize

LogFileSize Property

Description

Returns or sets a Long value specifying the maximum log-file size for this NetShow Unicast Manager Admin control.

Syntax

NSUnicastMgr.LogFileSize

Remarks

When the maximum size is reached, the log file is reset.

The value of the LogFileSize property must be zero when you specify a non-zero value for LogFilePeriod.

See Also

LogFilePeriod


MaxBandwidth

MaxBandwidth Property

Returns or sets a Long value specifying the maximum aggregate bandwidth for the server.

Syntax

NSUnicastMgr.MaxBandwidth

Remarks

The maximum value for MaxBandwidth is 4 gigabits per second. This property returns or sets values in units of bits per second.

Example

NSUnicastMgr.MaxBandwidth = 104857600
' bandwidth was set to 100 megabits per second
MsgBox "max bandwidth is " & NSUnicastMgr.MaxBandwidth

See Also

MaxClients, MaxFileBitRate


MaxClients

MaxClients Property

Returns or sets a Long value specifying the maximum number of client connections.

Syntax

NSUnicastMgr.MaxClients

Remarks

Sets the maximum allowable concurrent clients on a server. By default, this property is set to the maximum value, 1,000 clients.

Example

NSUnicastMgr.MaxClients = 1000
' MaxClients set to maximum allowed value, 1,000
MsgBox "Client limit is " & NSUnicastMgr.MaxClients

See Also

MaxBandwidth, MaxFileBitRate


MaxFileBitRate

MaxFileBitRate Property

Returns or sets a Long value specifying the maximum bit-rate per file. This value determines the maximum bandwidth resources that may be consumed by a client.

Syntax

NSUnicastMgr.MaxFileBitRate

Remarks

The maximum value for MaxFileBitRate is 3 megabits per second. The units it returns or sets are bits per second.

Example

NSUnicastMgr.MaxFileBitRate = 3145728
' MaxFileBitRate set to 3 megabits per second
MsgBox "max bandwidth is " & NSUnicastMgr.MaxFileBitRate

See Also

MaxBandwidth, MaxClients


ProxyHostName

ProxyHostName Property

Returns or sets a String value specifying the proxy host name.

Syntax

NSUnicastMgr.ProxyHostName

Remarks

NetShow supports HTTP stream distribution among NetShow servers. For example, the server connected to this instance of the Unicast Manager control could be distributing streams to multiple downstream servers. It may try, using HTTP, to connect to a server behind a firewall. This property returns the name of the proxy server to which this server is currently connected.

See Also

ProxyUser, SetProxyAuthenticationInfo, EnableProxy


ProxyUser

ProxyUser Property

Returns a String value specifying the user ID that is used for proxy authentication.

Syntax

NSUnicastMgr.ProxyUser

Remarks

NetShow supports HTTP stream distribution among NetShow servers. For example, the server connected to this instance of the Unicast Manager control could be distributing streams to multiple downstream servers. It may try, using HTTP, to connect to a server behind a firewall. This property returns the username used if this server is challenged by a proxy server.

See Also

SetProxyAuthenticationInfo, ProxyHostName, EnableProxy


Server

Server Property

Returns or sets a String value specifying the name of the currently connected NetShow unicast server, or connects to a new server.

Syntax

NSUnicastMgr.Server

Remarks

After you connect to a server, you can connect to another server by setting the Server property again. To disconnect from a server, set Server to NULL.

Example

MsgBox NSUnicastMgr.Server      ' show current connection
NSUnicastMgr.Server = Null      ' disconnect
NSUnicastMgr.Server = "SERVER9" ' connect to server SERVER9


ServerEvents

ServerEvents Property

A Boolean value specifying whether server events are enabled or disabled for this instance of the Netshow Unicast Manager Admin control.

Syntax

NSUnicastMgr.ServerEvents

Remarks

The default value for ServerEvents is True. Server events are OnServerOffline, OnServerOnline, and OnEventBacklogReached.

Example

If NSUnicastMgr.ServerEvents = False Then
  MsgBox "Server events are disabled"
End If

See Also

OnServerOffline, OnServerOnline


ServerStatus

ServerStatus Property

The ServerStatus property returns a Long value specifying the current status of the server.

Syntax

NSUnicastMgr.ServerStatus

Remarks

The Server property returns an error that indicates whether or not the specified server is running; however, under certain conditions the server may be running and still refusing to allow client connections. For example, a registered authentication plug-in failing to load at startup will not prevent the server from running and accepting configuration changes. However, because the server can not verify a client’s identity, it will not allow connections.

This property is an NSOADM_SERVER_STATUS enumeration, and returns one of the following values:

Value | Mnemonic | Description
0 | NSOADM_SERVER_RUNNING | The server is fully functional and allowing client connections.
1 | NSOADM_SERVER_FAULTED | An error occurred during initialization and the server is NOT allowing clients to connect.

See Also

Server


VirtualRoots

VirtualRoots Property

Obtains a collection object of all virtual roots.

Syntax

NSUnicastMgr.VirtualRoots

Example

For Each VirtualRoot in NSUnicastMgr.VirtualRoots
 ' show the path of each virtual root
 MsgBox VirtualRoot.DirectoryPath
Next

Remarks

A virtual root associates a folder on a server's hard disk with a folder that appears in the URL of a title. For example, you can create a virtual root called "myroot" on a server named "ASTRID" that is associated with the folder "c:\myrootfiles." Then a file named "myfile.asf" placed in the myrootfiles folder is referred to by the URL mms://astrid/myroot/myfile.asf


Objects Managed by the Unicast Manager Control

Objects Managed by the Unicast Manager Admin Control

The Unicast Manager control manages the following objects:

Object | Description
AuthenticationPlugins | Collection of AuthenticationPlugin objects.
AuthenticationPlugin | Contains information about each authentication plug-in.
Clients | Collection of Client objects.
Client | Contains information on each client.
EventPlugins | Collection of EventPlugin objects.
EventPlugin | Contains information about each event notification/authorization object.
VirtualRoots | Collection of VirtualRoot objects.
VirtualRoot | Contains information on each virtual root.

The following chart depicts the hierarchy of objects managed by the Unicast Manager Admin control:


Clients Collection Object Reference

The Clients collection object is a collection of Client objects.

The Clients collection object has the following properties:

Property | Read/Write | Description
Count | R | Returns the number of Client objects in the collection.
Item | R | Returns a single client from the collection.


Clients.Count

Clients.Count Property

Returns the number of Client objects in a Clients collection object.

Syntax

NSUnicastMgr.Clients.Count

Remarks

While the Clients object is a zero-based array (starting at zero), the Count property returns the number of clients starting with one.

Example

' display number of clients
MsgBox NSUnicastMgr.Clients.Count
' display Port ID of the last client
MsgBox NSUnicastMgr.Clients( NSUnicastMgr.Count – 1 ).PortID


Clients.Item

Clients.Item Property

Returns the Client object as specified by an index value.

Syntax

NSUnicastMgr.Clients.Item( Index )

Remarks

Item is the default property for this object, and it need not be specified explicitly. Note the two equivalent forms of syntax in the following example

Example

' display Port ID of the first client
MsgBox NSUnicastMgr.Clients.Item( 0 ).PortID
' display Port ID of the last client
MsgBox NSUnicastMgr.Clients( NSUnicastMgr.Count – 1 ).PortID


Client Object Reference

The Client object contains methods and properties for each client currently connected to the server.

The Client object has the following method:

  • Disconnect – Removes a client.

The Client object has the following properties:

Property | Read/Write | Description
ClientID | R | Returns the ID of a client.
Filename | R | Returns the name of the file being played by a client.
IPAddress | R | Returns the IP address of a client.
PortID | R | Returns the Port ID used by a client.
Status | R | Returns the current state of a client.


Client.ClientID

Client.ClientID Property

Returns the ID of the Client object.

Syntax

NSUnicastMgr.Client.ClientID

Remarks

The ClientID is a unique value that identifies each client.

Example

'show the ID of the second client in the collection
Set SecondClient = NSUnicastMgr.Clients.Item( 1 )
MsgBox SecondClient.ClientID


Client.Disconnect

Client.Disconnect Method

Removes the specified client.

Syntax

NSUnicastMgr.Client.Disconnect

Return Values

Returns an ActiveX HRESULT error code.

Example

The following example shows how to disconnect clients that are not in a particular IP subnet. It disconnects all the clients that are not on a particular class C subnet (where the first three octets in the address are set, such as: 123.4.140.xxx).

Sub OutsidersBeGone( subnet )
   For i = 0 to NSUnicastMgr.Clients.Count
      TheClient = NSUnicastMgr.Clients( i )
      ' check if the client is on the same subnet
      If StripSubnet( TheClient.IPAddress ) <> StripSubnet(subnet)) Then
      ' client is on another subnet. Show a descriptive
      ' message about the client
          MsgBox "Client Disconnected:"             & vbCrLf & _
                 "ClientID: " & TheClient.ClientID  & vbCrLf & _
                 "Address:  " & TheClient.IPAddress & vbCrLf &_
                 "Port:     " & TheClient.PortID
          TheClient.Disconnect
      End If
   Next
End Sub

Function StripSubnet( ip )
' strips the last octet off an IP address
   StripSubnet = Left( ip, ( InstrRev(ip,".", -1, 1 )) - 1 )
End Function


Client.Filename

Client.Filename Property

This property returns a String value containing the name of the file currently opened by the client.

Syntax

NSUnicastMgr.Client.FileName


Client.IPAddress

Client.IPAddress Property

Returns the IP address of the client.

Syntax

NSUnicastMgr.Client.IPAddress

Example

' show the IP of the second client in the collection
Set SecondClient = NSUnicastMgr.Clients.Item( 1 )
MsgBox SecondClient.IPAddress


Client.PortID

Client.PortID Property

Returns the port ID currently being used by this client.

Syntax

NSUnicastMgr.Client.PortID

Example

' show the Port of the second client in the collection
Set SecondClient = NSUnicastMgr.Clients.Item( 1 )
MsgBox SecondClient.PortID


Client.Status

Client.Status Property

This property returns a Long value specifying the current streaming state of the client.

Syntax

NSUnicastMgr.Client.Status

Remarks

This property returns one of the following values:

Value | Meaning
0 | None
1 | Open
2 | Playing


VirtualRoots Collection Object Reference

The VirtualRoots collection object is a collection of VirtualRoot objects.

The VirtualRoots collection object has the following methods:

Methods | Description
Add | Adds a VirtualRoot object to the VirtualRoots collection object.
Remove | Removes a specified VirtualRoot object from the VirtualRoots collection object.
SetAsHome | Sets the specified virtual root as the home root.

The VirtualRoots collection object has the following properties:

Properties | Read/Write | Description
Count | R | Gets the number of objects in a collection.
Item | R | Selects a specific item in a collection.


VirtualRoots.Count

VirtualRoots.Count Property

Returns the number of VirtualRoot objects in a VirtualRoots collection object.

Syntax

NSUnicastMgr.VirtualRoots.Count

Example

' display alias of the first root
MsgBox NSUnicastMgr.VirtualRoots.Item( 0 ).Alias
' display Port ID of the last client
MsgBox NSUnicastMgr. VirtualRoots( NSUnicastMgr.Count – 1 ).Alias

See Also

VirtualRoot, VirtualRoots


VirtualRoots.Item

VirtualRoots.Item Property

Returns the VirtualRoot object as specified by the Index value.

Syntax

NSUnicastMgr.VirtualRoots.Item( Index )

Parameters

Index

The index value is defined as a variant type. It can be expressed in the following different ways:

Syntax | Type | Definition
Item( 0 ) | Integer | Position of the element in the collection.
Item( “0” ) | String | Position of the element in the collection.
Item( 0.0 ) | Real | Position of the element in the collection.
Item( “Alias” ) | String | The alias name of the virtual root.
Item( “\Path\Dir” ) | String | The directory path of the virtual root.

String values are assumed to be the alias name or directory path, unless the search for a corresponding virtual root fails. Then the system attempts to convert the string to a number and search for the virtual root by its position in the collection.

Remarks

Item is the default property for this object, and it need not be specified explicitly. Note the two equivalent forms of syntax in the following example

Example

' display alias of the first root
MsgBox NSUnicastMgr.VirtualRoots.Item( 0 ).Alias
' display Port ID of the last client
MsgBox NSUnicastMgr. VirtualRoots( NSUnicastMgr.Count – 1 ).Alias

See Also

VirtualRoot, VirtualRoots


VirtualRoots.Add

VirtualRoots.Add Method

Adds a VirtualRoot object to the VirtualRootscollection object.

Syntax

NSUnicastMgr.VirtualRoots.Add( AliasName, VirtualDirectory, [maxClients], [maxBandwidth] )

Parameters

AliasName

A unique String specifying the name of the virtual root being added.

VirtualDirectory

A String specifying the directory for the virtual root.

maxClients

An optional Long value specifying the maximum number of clients allowed access to this virtual root.

maxBandwidth

An optional Long value specifying the maximum bandwidth allowed for this virtual root.

Return Values

Returns an ActiveX HRESULT error code.

Remarks

The Add method creates a virtual root, but does not create the directory for the root.

Example

The following script creates two virtual roots. The second root is contained within the first. However, their respective directories are not nested.

NSUnicastMgr.VirtualRoots.Add "LiveOpera", "d:\liveopera"
' create nested root with non-nested directories
NSUnicastMgr.VirtualRoots.Add "LiveOpera/Britten", "d:\britten"
' create root for stream on another server
NSUnicastMgr.VirtualRoots.Add "Distribution", "msbd://server/station"

See Also

VirtualRoot, VirtualRoots, VirtualRoot.AliasName


VirtualRoots.Remove

VirtualRoots.Remove Method

Removes the VirtualRoot object specified by the AliasName parameter from the VirtualRoots collection object.

Syntax

NSUnicastMgr.VirtualRoots.Remove( Index )

Parameters

Index

The index value is defined as a variant type. It can be expressed in the following different ways:

Syntax | Type | Definition
Item( 0 ) | Integer | Position of the element in the collection.
Item( “0” ) | String | Position of the element in the collection.
Item( 0.0 ) | Real | Position of the element in the collection.
Item( “Alias” ) | String | The alias name of the virtual root.
Item( “\Path\Dir” ) | String | The directory path of the virtual root.

String values are assumed to be the alias name or directory path unless the search for a corresponding virtual root fails. Then the system attempts to convert the string to a number and search for the virtual root by its position in the collection.

Return Values

Returns an ActiveX HRESULT error code.

Example

' remove virtual root with alias "Unnecessary Flotsam"
NSUnicastMgr.VirtualRoots.Remove "Unnecessary Flotsam"

See Also

VirtualRoot, VirtualRoots, VirtualRoot.AliasName


VirtualRoot.SetAsHome

VirtualRoots.SetAsHome Method

This method sets the virtual root specified by the index value to be the home root.

Syntax

NSUnicastMgr.VirtualRoots.SetAsHome( Index )

Parameters

Index

The index value is defined as a variant type. It can be expressed in the following different ways:

Syntax | Type | Definition
Item( 0 ) | Integer | Position of the element in the collection.
Item( “0” ) | String | Position of the element in the collection.
Item( 0.0 ) | Real | Position of the element in the collection.
Item( “Alias” ) | String | The alias name of the virtual root.
Item( “\Path\Dir” ) | String | The directory path of the virtual root.

String values are assumed to be the alias name or directory path unless the search for a corresponding virtual root fails. Then the system attempts to convert the string to a number and search for the virtual root by its position in the collection.

Remarks

The home root is the starting point of the virtual root hierarchy. The system searches for all virtual roots in the collection relative to the home root specified by the VirtualRoot.Directory property specified by the Index parameter of this method.

See Also

VirtualRoot.DirectoryPath


VirtualRoot Object Reference

The VirtualRoot object contains properties for each current virtual root.

The VirtualRoot object has the following properties:

Property | Read/Write | Description
AliasName | R | Returns the alias used by the virtual root.
DirectoryPath | RW | Returns the virtual root directory path on the server.
MaxBandWidth | RW | Sets the maxium bandwidth allowed.
MaxClients | RW | Sets the maximum number of clients allowed.


VirtualRoot.AliasName

VirtualRoot.AliasName Property

Returns the alias used by the virtual root.

Syntax

NSUnicastMgr.VirtualRoot.AliasName

Example

' display a list of all virtual root aliases
NSUnicastMgr.Connect "LocalHost"
For i = 0 to NSUnicastMgr.VirtualRoots.Count
   Document.Write NSUnicastMgr.VirtualRoots( i ).AliasName, "<BR>"
Next


VirtualRoot.DirectoryPath

VirtualRoot.DirectoryPath Property

Returns the virtual root directory path on the server.

Syntax

NSUnicastMgr.VirtualRoot.DirectoryPath

Example

' display a list of all virtual root directory paths
NSUnicastMgr.Connect "LocalHost"
For i = 0 to NSUnicastMgr.VirtualRoots.Count
   Document.Write NSUnicastMgr.VirtualRoots( i ).DirectoryPath, "<BR>"
Next


VirtualRoot.MaxBandwidth

VirtualRoot.MaxBandwidth Property

Returns or sets a Long value specifying the maximum aggregate bandwidth for this virtual root.

Syntax

NSUnicastMgr.VirtualRoot.MaxBandwidth

Remarks

Exceeding the limit set by this property triggers an OnMaxBandwidth event. The last parameter of the event specifies which virtual root exceeded the bandwidth limit.

The initial value for this property is set when the VirtualRoot.Add method is called.

See Also

VirtualRoot.MaxClients


VirtualRoot.MaxClients

VirtualRoot.MaxClients Property

Returns or sets a Long value specifying the maximum number of client connections for this virtual root.

Syntax

NSUnicastMgr.VirtualRoot.MaxClients

Remarks

Exceeding the limit set by this property triggers an OnMaxClients event. The last parameter of the event specifies which virtual root exceeded the client limit.

The initial value for this property is set when the VirtualRoot.Add method is called.

See Also

VirtualRoot.MaxBandwidth


EventPlugins Collection Object

The EventPlugins collection object is a collection of EventPlugin objects. The EventPlugins collection object has the following properties.

Properties | Read/Write | Description
Item | R | Indicates a specific element of the collection object.
Count | R | Returns the number of EventPlugin objects in the collection.

Example

The following example code displays the description of each EventPlugin object in the collection in message boxes:

For i=1 to CInt(NSUnicastMgr1.EventPlugins.Count )
  MsgBox NSUnicastMgr1.EventPlugins.Item( i-1 ).Description
Next

See Also

EventPlugin


EventPlugins.Count

EventPlugins.Count Property

Returns the number of EventPlugin objects in the collection.

Syntax

NSUnicastMgr.EventPlugins.Count


EventPlugins.Item

EventPlugins.Item Property

Returns the EventPlugin object specified by the Element value.

Syntax

NSUnicastMgr.EventPlugins[.Item ]( Index )

Remarks

Item is the default property for this collection object and, as such, it is optional.


EventPlugin Object

The EventPlugin object exposes the following properties for each event notification and authorization plug-in:

Property | Read/Write | Description
Author | R | The name of the plug-in’s author.
CLSID | R | The class ID of the plug-in.
Copyright | R | The plug-in’s copyright information.
Description | R | Description of the plug-in.
Enabled | RW | Enable/Disable this plug-in.
LastError | R | Indicates the last error send by the plug-in.
Status | R | Indicates the current status of the plug-in.

See Also

EventPlugins

For information about creating and registering event notification and authorization plug-ins, see the NetShow Event Notification and Authorization API.


EventPlugin.Author

EventPlugin.Author Property

Returns a string value containing the name of the plug-in’s author.

Syntax

NSUnicastMgr.EventPlugins[.Item].Author

Remarks

The author’s name for each plug-in is stored in the registry.

See Also

EventPlugin


EventPlugin.CLSID

EventPlugin.CLSID Property

Returns a String value containing the universally unique class identifier (CLSID) of the plug-in.

Syntax

NSUnicastMgr.EventPlugins[.Item].CLSID

Remarks

The CLSID of each plug-in is stored in the registry.

See Also

EventPlugin


EventPlugin.Copyright

EventPlugin.Copyright Property

Returns a String value containing copyright information about the plug-in.

Syntax

NSUnicastMgr.EventPlugins[.Item].Copyright

Remarks

The copyright information for each plug-in is stored in the registry.

See Also

EventPlugin


EventPlugin.Description

EventPlugin.Description Property

Returns or sets a String value containing a description of the plug-in.

Syntax

NSUnicastMgr.EventPlugins[.Item].Description

Remarks

The plug-in description is stored in the registry.

See Also

EventPlugin


EventPlugin.Enabled

EventPlugin.Enabled Property

Sets a Boolean value specifying whether this plug-in is enabled or disabled.

Syntax

NSUnicastMgr.EventPlugins[.Item].Enabled

Remarks

The NetShow server checks the registry for this value at startup.

Plug-ins can only be enabled by the server at startup. This property sets a flag that is checked by the server at startup to determine whether or not to enable this plug-in. To check the actual enabled state of the plug-in, use the Plugin.Status property.

See Also

EventPlugin, Status


EventPlugin.LastError

EventPlugin.LastError Property

This property returns a Long value indicating the last error sent by the plug-in.

Syntax

NSUnicastMgr.EventPlugin.LastError

Remarks

This property only returns valid results after checking the Status property.

See Also

Status


EventPlugin.Status

EventPlugin.Status Property

This property returns a Long value indicating the current status of the plug-in.

Syntax

NSUnicastMgr.EventPlugin.Status

Remarks

The value returned by this property is a combination of the following:

Value | Mnemonic | Description
1 | NSOADM_PLUGIN_ERROR | Indicates a fatal error occurred and the plug-in could not be loaded.
2 | NSOADM_PLUGIN_LOADED | Indicates the plug-in loaded successfully.
4 | NSOADM_PLUGIN_ENABLED | Indicates the plug-in is enabled (i.e., it will be used by the server).
8 | NSOADM_PLUGIN_RUNNING | Indicates the plug-in is up and running successfully.
16 | NSOADM_PLUGIN_LOAD_NEXT_RESTART | Indicates the plug-in will be enabled when the server is restarted.
32 | NSOADM_PLUGIN_UNLOAD_NEXT_RESTART | Indicates the plug-in will be unloaded when the server is restarted.

See Also

LastError


AuthenticationPlugins Collection Object

The AuthenticationPlugins collection object is a collection of AuthenticationPlugin objects. The AuthenticationPlugins collection object has the following properties.

Property | Read/Write | Description
Count | R | Returns the number of AuthenticationPlugin objects in the collection.
Item | R | Indicates a specific element of the collection object.

Example

The following example code displays the description of each AuthenticationPlugin object in the collection in message boxes:

For i=1 to CInt( NSUnicastMgr1.AuthenticationPlugins.Count )
  MsgBox NSUnicastMgr1.AuthenticationPlugins.Item( i-1 ).Description
Next

See Also

AuthenticationPlugin


AuthenticationPlugins.Count

AuthenticationPlugins.Count Property

Returns the number of AuthenticationPlugin objects in the collection.

Syntax

NSUnicastMgr.AuthenticationPlugins.Count


AuthenticationPlugins.Item

AuthenticationPlugins.Item Property

Returns the AuthenticationPlugin object specified by the Index value.

Syntax

NSUnicastMgr.AuthenticationPlugins[.Item ]( Index )

Remarks

Item is the default property for this collection object and, as such, it is optional.


AuthenticationPlugin Object

The AuthenticationPlugin object exposes the following properties for each event notification and authorization plug-in:

Property | Read/Write | Description
Enabled | RW | Enable/Disable this plug-in.
Description | R | Description of the plug-in.
CLSID | R | The class ID of the plug-in.
Author | R | The name of the plug-in’s author.
Copyright | R | The plug-in’s copyright information.
LastError | R | The code of the last occurred error of the plug-in.
Status | R | Status of the event plugin.

See Also

AuthenticationPlugins collection object

For information about creating and registering authentication plug-ins, see the NetShow Authentication API documentation.


AuthenticationPlugin.Author

AuthenticationPlugin.Author Property

Returns a string value containing the name of the plug-in’s author.

Syntax

NSUnicastMgr.AuthenticationPlugins[.Item].Author

Remarks

The author’s name for each plug-in is stored in the registry.

See Also

AuthenticationPlugin object


AuthenticationPlugin.CLSID

AuthenticationPlugin.CLSID Property

Returns a String value containing the universally unique class identifier (CLSID) of the plug-in.

Syntax

NSUnicastMgr.AuthenticationPlugins[.Item].CLSID

Remarks

The CLSID of each plug-in is stored in the registry.

See Also

AuthenticationPlugin object


AuthenticationPlugin.Copyright

AuthenticationPlugin.Copyright Property

Returns a String value containing copyright information about the plug-in.

Syntax

NSUnicastMgr.AuthenticationPlugins[.Item].Copyright

Remarks

The copyright information for each plug-in is stored in the registry.

See Also

AuthenticationPlugin object


AuthenticationPlugin.Description

AuthenticationPlugin.Description Property

Returns or sets a String value containing a description of the plug-in.

Syntax

NSUnicastMgr.AuthenticationPlugins[.Item].Description

Remarks

The description of each plug-in is stored in the registry.

See Also

AuthenticationPlugin object


AuthenticationPlugin.Enabled

AuthenticationPlugin.Enabled Property

Returns or sets a Boolean value specifying whether this plug-in is enabled or disabled.

Syntax

NSUnicastMgr.AuthenticationPlugins[.Item].Enabled

See Also

AuthenticationPlugin object


AuthenticationPlugin.Status

AuthenticationPlugin.Status Property

Returns a Long value specifying the current status of the Authentication plug-in.

Syntax

NSUnicastMgr.AuthenticationPlugins[.Item].Status

Remarks

The value returned by this property is a combination of the following:

Value | Mnemonic | Description
1 | NSOADM_PLUGIN_ERROR | Indicates a fatal error occurred and the plug-in could not be loaded.
2 | NSOADM_PLUGIN_LOADED | Indicates the plug-in loaded successfully.
4 | NSOADM_PLUGIN_ENABLED | Indicates the plug-in is enabled (i.e. it will be used by the server).
8 | NSOADM_PLUGIN_RUNNING | Indicates the plug-in is up and running successfully.
10 | NSOADM_PLUGIN_LOAD_NEXT_RESTART | Indicates the plug-in will be enabled when the server is restarted.
20 | NSOADM_PLUGIN_UNLOAD_NEXT_RESTART | Indicates the plug-in will be unloaded when the server is restarted.


AuthenticationPlugin.LastError

AuthenticationPlugin.LastError Property

Returns a Long value specifying the code of the last error of the plug-in.

Syntax

NSUnicastMgr.AuthenticationPlugins[.Item].LastError

Remarks

This property only returns valid results after checking the Status property.


About the Netshow Unicast TraceView Control

The NetShow Unicast TraceView control provides an easy-to-use interface for monitoring NetShow unicast activity. Its grapical user interface is used to display a list of events initiated by the NetShow server. The display includes a description of events and the date and time when they were triggered. The TraceView control also exposes methods and supports events for programmatically manipulating the TraceView control.


Using the NetShow Unicast TraceView Control

You can program the TraceView control to perform the following functions:

  • To pause and resume event monitoring.
  • To clear the display of the event logging.
  • To select event types for monitoring. The selection includes the Server, Client, Admin, and/or Alert events.

To enable the TraceView control embedded in your applications, you must initialize the control by calling its SetServer method. This connects the TraceView control to the server and lets the control start to receive events for display.

The CLSID of NetShow Unicast TraceView is 24DCD5F2-6DBB-11D1-BEF5-00805FBE84A6


Reference of the NetShow Unicast TraceView Control

The NetShow Unicast TraceView control exposes the following events and methods for monitoring NetShow unicast events.


TraceView Methods

Method | Description
ClearTrace | Clears the TraceView display.
PauseTrace | Pause/Resume tracing.
SetServer | Connects to a title server.
TraceProperties | Invokes a dialog box for users to select event filters.


TraceView.ClearTrace Method

The TraceView.ClearTrace method clears all event notifications from the trace view display.

Syntax

TraceView.ClearTrace

Parameters

This method has no parameters.


TraceView.PauseTrace Method

The TraceView.PauseTrace method pauses or resumes tracing.

Syntax

TraceView.PauseTrace( pause )

Parameters

pause

This parameter indicates one of the following Boolean values:

Value | Description
True | Pause tracing
False | Resume tracing


TraceView.SetServer Method

The TraceView.SetServer method connects to a NetShow server.

Syntax

TraceView.SetServer( servername [, eventproxy])

Parameters

servername

A String value indicating the title server to connect to.

eventproxy

An optional String value specifying the name of the server where the NetShow Monitor Service is running.


TraceView.TraceProperties Method

The TraceView.TraceProperties method displays a property sheet of trace options.

Syntax

TraceView.TraceProperties

Parameters

This method has no parameters.

Remarks

The property sheet displayed by this method allows the user to filter the types of events sent to the TraceView control and set the maximum buffer size.


TraceView Events

Event | Description
OnTraceStateChange | Fired when the user clears, resumes, or pauses a trace.


TraceView.OnTraceStateChange Event

The TraceView.OnTraceStateChange event is triggered when a user clears, resumes, or pauses a trace.

Syntax

TraceView.OnTraceStateChange( newstate )

Parameters

newstate

This parameter indicates the new state of trace. Possible values for this parameter include the following:

Value | State
0 | Active
1 | Paused


Unicast Manager Samples

The following samples illustrates how to use functionality exposed by the Unicast Manager controls using HTML, VBScript, and C programming languages.

Sample | Description
NetShow Unicast Server Monitor | This simple sample, in HTML and VBScript, displays configuration settings of a NetShow unicast server, and monitors clients connection as well.
NetShow Unicast TraceView Control | This simple HTML/VBScript sample uses the Unicast TraceView control to log unicast events. The user can choose to monitor all four types of events.
NetShow Unicast Administration Utility | This sample is a console application written in C and illustrates how to use the Admin control within a C application.

To test the SDK sample, you should have the appropriate ActiveX controls installed in your system. It is recommended that you run these samples on a machine that has NetShow installed. To download the complete suite of NetShow products visit the NetShow web site http://www.microsoft.com/NetShow


NetShow Station Manager Programming Guide

[This is preliminary documentation and subject to change.]

The Station Manager Control component of the Microsoft® NetShow™ SDK provides conceptual information about the NetShow Station Manager Control, as well as guidelines for using it in HTML, Microsoft Visual Basic®, and Microsoft Visual C++® programming environments. It is divided into the following parts:

Part | Description
About the Station Manager Control | Architecture of the control
Using the Station Manager Control | Guide to using and programming the control
Station Manager Control Reference | Reference to the control events, methods, and properties
Station Manager Control Samples | Sample applications using Station Manager controls


About the Station Manager Control

The NetShow Station Manager Control is a Microsoft ActiveX® control that allows an administrator to configure broadcast stations, and start and stop streams. This guide describes the functionality exposed by the control for creating custom administration applications and integrating NetShow into other software products.

Note Starting with NetShow version 3.0, the term station is used in place of the previous term channel to define how a stream is to be delivered. However, the station objects managed by the Station Manager still reflect the old terminology. For example, the event fired when a station is closed is still called OnChannelClose. Likewise, the Channels collection object contains Channel objects, which are referred to as stations. Code written for previous versions of NetShow will still work with the current version.

The Station Manager Control exposes attributes for performing the following tasks:

  • Creating, deleting, and managing stations.
  • Creating, deleting, and managing streams.
  • Creating, deleting, and managing clients.
  • Creating, deleting, and managing host addresses.
  • Creating, deleting, and managing Station Manager objects.

The NetShow Station Manager Control can be used directly in HTML pages (with or without Visual Basic Scripting) and in Visual Basic and Visual C++ applications. It exposes Station services administration functionality through a set of OLE automation interfaces. Those same properties and events are available in any programming environment that supports ActiveX controls. For more information on OLE automation and ActiveX controls, see any COM/OLE or ActiveX documentation. A list of additional information resources is in the More Information and Examples section of the Media Player section of the SDK.

For more information about NetShow, visit the NetShow home page at http://www.microsoft.com/netshow/.

Support for current versions of NetShow Station Manager is limited to computers running Microsoft Windows NT® Workstation or Windows NT Server version 4.0 operating systems. However the Station Manager Control is also supported on computers running Microsoft Windows® 95 and Windows98.


Station Manager Stations

Each station defines the delivery mechanism for a stream. For example, a station contains information about the station name, the multicast address of the destination, the station formats, and so on. A station itself does not contain media content, but rather describes how content can be delivered.

Each station can have one or more station formats, which contain information such as bit rate, packet size, and stream descriptors.

Each station format has at least one stream descriptor, which contains information such as the descriptor type, description, width, and type.


Station Manager Streams

Streams are packets of data that define multimedia content. Streams can be started, stopped, closed, and restarted. Streams also have sources, aliases, and content types, and can be associated with a station.


Station Manager Clients

Each station can be associated with one or more clients. Clients can be the NetShow Encoder, or other NetShow Station Managers. Clients can also be Microsoft Media Players connected through the Media Streaming Broadcast Distribution (MSBD) protocol. Essentially all clients are connected through the MSBD or HTTP protocols.


Station Manager Host Addresses

Each station is associated with at least one host address. A host address is the address used by the server network card to broadcast.


Station Manager Objects

The Station Manager Control manages a number of objects, many of which are collections of other objects.

The Station Manager object manages the following objects:

  • Channels collection object, which contains a number of Channel objects.
  • Channel objects, each of which may manage a ChannelFormats collection object.
  • ChannelFormats collection object, which contains a number of ChannelFormat objects.
  • ChannelFormat objects, each of which may manage a StreamDescriptors collection object.
  • StreamDescriptors collection object, which contains a number of StreamDescriptor objects.
  • StreamDescriptor objects.
  • Streams collection object, which contains a number of Stream objects.
  • Stream objects.
  • Clients collection object, which contains a number of Client objects.
  • Client objects.
  • HostAddresses collection object, which contains a number of Address objects.
  • Address objects.

The following chart depicts the hierarchy of the collections and objects managed by the Station Manager control:

The Station Manager object has several events, methods, and properties. In addition, each object managed by the Station Manager Control may have its own events, methods, or properties.


Using the Station Manager Control

Microsoft® NetShow™ uses a Microsoft ActiveX® control to manage the flow of content from a NetShow server. See the Microsoft ActiveX SDK for more information about ActiveX controls.

To use the Station Manager Control (Nschmgr.ocx), you must install NetShow Server, or copy the Nschmgr.ocx control to your computer and register it with the RegSvr32 application. Nschmgr.ocx requires Microsoft Windows NT® Service Pack 3 to operate correctly.


Creating a Multicast with the SDK

Creating an On-Demand Multicast with the SDK

You can set up and start a multicast using the NetShow SDK instead of the NetShow administrative application. This section outlines the steps needed to set up a basic multicast to distribute content on demand, using only the SDK. The following examples are written from the perspective of doing local administration.

Instantiate the Station Manager Object

Create an instance of the station manager object. The following code is straight HTML code, so it should not be within a SCRIPT section.

<OBJECT ID="MCM" HEIGHT=1 WIDTH=1
   CLASSID="CLSID:B00464B3-67D4-11D0-A464-00C04FC29CFB">
</OBJECT>

Connect to the NetShow Server

Open a connection to the NetShow server. In this example, the new station manager object is called MCM. It connects to a NetShow server running on the same computer where the script is being run. However, as long as the Station Manager Control is installed locally, you can also connect to a remote computer that is running the NetShow server.

MCM.Connect "LocalHost"

Create a New Station

You create a station for the multicast using the Open method.. In this example the first parameter for the Open method specifies a station named My Station. The second parameter specifies that all administrative clients on the NetShow server will have full read, write, and delete permissions. The Open method returns a Channel object, which can be referred to by the variable MyStation.

Set MyStation = MCM.Channels.Open( "My Station", 7 )

Set Station Properties

Once you have a station to work with, you set the properties you need. The following properties must be set before you can multicast over the station. Many of the optional descriptive properties have not been set in this example, but if you do want to set them, this is where you can do it.

Note: When you set the IPAddress and Port properties, ensure that the values don't duplicate those of an existing station. It can be difficult to track down duplicate multicast servers.

MyStation.MulticastAddress = "238.8.217.46"
MyStation.Port = 13767

Specify Delivery Options

You must also specify if the multicast is intended for distribution to other servers, for viewing in a player, or both. In this example, the distribution mode has been set to allow the multicast to be viewed in a player.

MyStation.DeliveryMode = MCM_DM_SESSIONLESS_3PH

Create a Station Format

The station must contain at least one station format to tell players how to render the content in the multicast. The station format is contained in a ChannelFormat object. In this example, the .asf file used as the multicast source is also used to specify the station format:

MyStation.ChannelFormats.Add "c:\ASFRoot\welcome.asf", _
   3MCM_ASF_CH_FORMAT_FILE

Create an NSC File

When you have your station set up, you need to export it into an .nsc file that is posted for easy access by a client. In this example, the .nsc file is written into the home folder of a Web server on the local computer. The second parameter specifies that an old file with the same name can be overwritten.

MyStation.WriteNSC "c:\inetpub\wwwroot\mynsc.nsc", "True"

Create a Stream

Now that the station has been created, you create a stream to play within it. Use the Open method to create a stream. In this example, the new stream is given the name "MyStream", with a unicast URL as its source. You must specify the access rights clients can have to the stream. The enumeration for access right is defined as MCM_PA_READ, MCM_PA_WRITE, MCM_PA_DELETE, and MCM_PA_ALL.

Set MyStream = MCM.Streams.Open ("mms://astrid/welcome.asf", "MyStream", MCM_PA_READ)

Activate the Stream

Once you have a valid station and stream, you need to associate the stream with the station by activating it. A station can have only one active stream. If you have several streams, you can switch among them while the station multicasts. Clients listening to the station will receive content from the active stream, but cannot select which stream is active. That is up to you. In this case, we have only one stream to set as the active stream.

MyStation.SetActiveStream MyStream

Start the Multicast

All that is left to do is start the stream. In this example, we will start the stream at the beginning by specifying an opening position of zero milliseconds past the start of the file.

MyStream.Start 0

Playing the Multicast

Now your stream is being multicasted. A client on a subnet that receives the multicast can now connect and play the multicast.


Multicasting a Live Stream

The process for multicasting a live stream (rather than multicasting an .asf file) is similar to that for multicasting a file. The following example shows how to set up a simple multicast of a live stream. However, this multicast would likely produce unsatisfactory results since the stream is being encoded on the same computer where the multicast originates. For best results, you may need to run the encoder on a dedicated computer.

The main difference between this example and the previous one is that the stream is distributed as an MSBD protocol stream, not an .asf file. Consequently, the stream format is retrieved from an .asd file that was created by the encoder. This accounts for the differences in the last parameter for the ChannelFormats.Add method.

To view this multicast, a player would open the location http://astrid/myNSC.nsc.

MCM.Connect "LocalHost"
Set MyStation = MCM.Channels.Open( "MyStation", MCM_PA_ALL_ACCESS )
MyStation.MulticastAddress = "238.8.217.48"
MyStation.Port = 14767
MyStation.DeliveryMode = MCM_DM_SESSIONLESS_3PH
Set MyStream = MCM.Streams.Open ("msbd://astrid:1152", "MyStream", _
   MCM_PA_ALL_ACCESS)
MyStation.ChannelFormats.Add "c:\ASFRoot\Stream Formats\MyFormat.asd", _
   MCM_ASD_CH_FORMAT_FILE
MyStation.WriteNSC "c:\inetpub\wwwroot\MyStation.nsc", "True"
MyStation.SetActiveStream MyStream
MyStream.Start 0


Stopping Streams and Stations

The examples given so far in this section only create and start a multicast. You could stop and delete the stations and streams by using the NetShow Administrator, but you can also do it directly by using the NetShow SDK. For example, you can add a button in your HTML code to stop a stream:

<INPUT TYPE=BUTTON NAME=StopStream VALUE="Stop Stream">

and handling it with this code:

Sub StopStream_OnClick
  MyStream.Stop
End Sub

Beyond this, you can create full-featured applications to control every aspect of a multicast.


Station Manager Control Reference

This section lists the events, methods, and properties supported by the Station Manager Control.

Besides being an object in itself, the Station Manager Control also manages several other objects, each of which may have its own methods or properties.


Events for Station Manager Control

The Station Manager Control supports the following events:

Event | Fired When
OnChannelClose | A channel is closed.
OnChannelOpen | A channel is opened.
OnChannelPropertyChange | A channel property changes.
OnChannelStreamChange | A channel stream changes.
OnClientConnect | A client is connected.
OnClientDisconnect | A client is disconnected.
OnStreamArchiveClosed | A stream archive is closed.
OnStreamClose | A stream is closed.
OnStreamOpen | A stream is opened.
OnStreamPropertyChange | A stream property is changed.
OnStreamStart | A stream is started.
OnStreamStop | A stream is stopped.


OnChannelClose Event

This event is fired when a station is closed.

Syntax

NSChannelMgr_OnChannelClose( StationName, StationDesc, StationID )

Parameters

StationName

A String value specifying the name of the closed station.

StationDesc

A String to describe of the closed station.

StationID

A Long value specifying the station ID of the closed station.

Example

Sub NSChannelMgr_OnChannelClose (TheStation, Desc, ID)
  MsgBox "Station " & TheStation.Name & " closed"
End Sub

See Also

OnChannelOpen


OnChannelOpen Event

This event is fired when a station is opened.

Syntax

NSChannelMgr_OnChannelOpen( Station )

Parameters

Station

A Channel object.

Example

NSChannelMgr_OnChannelOpen Station

Example

Sub NSChannelMgr_OnChannelOpen( TheStation )
  MsgBox "Station " & TheStation.Name & " opened"
End Sub

See Also

OnChannelClose


OnChannelPropertyChange Event

This event is fired when a Channel object property changes.

Syntax

NSChannelMgr_OnChannelPropertyChange( Station )

Parameters

Station

A Channel object.


OnChannelStreamChange Event

This event is fired when a station has a new Stream object associated with it.

Syntax

NSChannelMgr_OnChannelStreamChange( Station, OldStream, NewStream )

Parameters

Station

A Channel object.

OldStream

The old stream object.

NewStream

The new stream object.

Remarks

If a stream did not exist before, a Null or Nothing value will be returned.

Example

Sub NSChannelMgr_OnChannelStreamChange (MyStation, OldSream, NewStream)
   Str = "Station " & MyStation.Name & " stopped playing "
   Str = Str + OldStream.Alias " and is now playing " & NewStream.Alias
   MsgBox Str
End Sub


OnClientConnect Event

This event is fired when a client is connected.

Syntax

NSChannelMgr_OnClientConnect( Client )

Parameters

Client

A Client object.

Example

Sub NSChannelMgr_OnClientConnect( Client )
  MsgBox "Client at " & Client.Address & "connected"
End Sub

See Also

OnClientDisconnect


OnClientDisconnect Event

This event is fired when a client is disconnected.

Syntax

NSChannelMgr_OnClientDisconnect( ClientAddress, DeliveryMode, ClientID )

Parameters

ClientAddress

A String value specifying the IP address of the disconnected client.

DeliveryMode

A Long value indicating the delivery mode of the disconnected client.

ClientID

A Long value indicating the client ID of the disconnected client.

Remarks

DeliveryMode values are an enumeration of type MCMDELIVERYMODE. The following values are supported by the Station Manager control:

Value | Mnemonic | Description
2 | MCM_DM_SESSIONLESS_3PH | Sessionless: data streamed via multicast with headers transferred to clients by some mechanism external to MCM
8 | MCM_DM_DISTRIBUTION | Distribution: data streamed via a point to point TCP connection

Example

Sub NSChannelMgr_OnClientDisconnect( Client, Mode, ID )
  Select Case Mode
    Case 2 str = "sessionless"
    Case 8 str = "distribution"
End Select
  MsgBox "Client at " & Client.Address & "dropped " & str _
    & "delivery mode connection"
End Sub

See Also

Channel.DeliveryMode


OnStreamArchiveClosed Event

This event is fired when a Stream object archive is closed.

Syntax

NSChannelMgr_OnStreamArchiveClosed( Stream, hResult )

Parameters

Stream

A Stream object.

hResult

A Long value specifying an ActiveX HRESULT error code.

Remarks

HRESULT values are listed in the nserror.h file.

See Also

Stream.ArchiveFile, Stream.ArchiveSize


OnStreamClose Event

This event is fired when a Stream is closed.

Syntax

NSChannelMgr_OnStreamClose( Source, StreamDesc, StreamID )

Parameters

Source

A String value indicating the source of the closed stream, for example: mms://netshow/sample.asf.

StreamDesc

A String value specifying the description of the closed stream.

StreamID

A Long value indicating the unique stream ID of the closed stream.

Example

Sub NSChannelMgr_OnStreamClose( Source, StreamDesc, StreamID )
  MsgBox StreamDesc & " at " & Source & " closed"
End Sub

See Also

Stream.Start, Stream.Stop, Streams.Open


OnStreamOpen Event

This event is fired when a Stream is opened.

Syntax

NSChannelMgr_OnStreamOpen( Stream )

Parameters

Stream

A Stream object.

Example

Sub NSChannelMgr_OnStreamOpen( TheStream )
  MsgBox "Stream at " & TheStream.Source & " opened"
End Sub

See Also

Stream.Start, Stream.Stop, Stream.Close


OnStreamPropertyChange Event

This event is fired when a Stream object property is changed.

Syntax

NSChannelMgr_OnStreamPropertyChange( Stream )

Parameters

Stream

A Stream object.

Example

Sub NSChannelMgr_OnPropertyChange (Stream)
  MsgBox Stream.Desc
End Sub


OnStreamStart Event

This event is fired when a Stream object is started.

Syntax

NSChannelMgr_OnStreamStart( Stream )

Parameters

Stream

A Stream object.

Example

Sub NSChannelMgr_OnStreamStart( Stream )
  MsgBox Stream.Desc & " started"
End Sub

See Also

Stream.Start, Stream.Stop, Stream.Close


OnStreamStop Event

This event is fired when a Stream object is stopped. A stream may be stopped, but not closed.

Syntax

NSChannelMgr_OnStreamStop( Stream, hRsult )

Parameters

Stream

A Stream object.

hResult

A Long value holding a Microsoft® ActiveX® HRESULT error code.

Example

Sub NSChannelMgr_OnStreamStart( Stream, hresult )
  If hresult Then
    MsgBox Stream.Desc & " stopped gracefully"
  Else
    MsgBox Stream.Desc & " is in trouble"
  End If
End Sub

See Also

Stream.Start, Stream.Stop, Stream.Close


Methods for Station Manager Control

The Station Manager Control supports the following methods:

Method | Description
Connect | Makes a connection to the Station Manager object.
SetProxyAuthenticationInfo | Sets HTTP proxy authentication credentials.


Connect Method

Makes a connection to a client.

Syntax

NSChannelMgr.Connect( [Machine] )

Parameters

Machine

A String value specifying the computer name for the connection.

Return Values

Returns an ActiveX HRESULT error code.

Example

On Error Resume Next
NSChannelMgr1.Connect "LocalHost"
If Err.Number = 0 then
  MsgBox "Connected to LocalHost"
Else
  MsgBox "Connection failed: " & Err.Description
End If


SetProxyAuthenticationInfo

SetProxyAuthenticationInfo Method

Sets HTTP proxy authentication credentials.

Syntax

NSChannelMgr.SetProxyAuthenticationInfo( bstrUser, bstrPasswd )

Parameters

bstrUser

A String value specifying the domain and user name. The domain is optional.

bstrPasswd

A String value specifying the password.

Return Values

Returns an ActiveX HRESULT error code.

Remarks

NetShow supports HTTP stream distribution among NetShow servers. For example, the server connected to this instance of the Unicast Manager control could be distributing streams to multiple downstream servers. It may try, using HTTP, to connect to a server behind a firewall. This method is used to set the username and password credentials needed to break through the firewall if this server is challenged by a proxy server.


Properties for Station Manager Control

The Station Manager Control supports the following properties:

Property | Read/Write | Description
Channels | R | Gets a Channels object.
HostAddresses | R | Gets a HostAddresses object.
Clients | R | Gets a Clients object.
Streams | R | Gets a Streams object.
Server | R | Gets the name of the server for the connection.
EnableHttpStreaming | RW | Enables or disables Http streaming.
EnableProxy | RW | Enables or disables the proxy server.
ProxyHostName | RW | Returns the proxy host name.
ProxyUser | R | Returns the user ID used for proxy authentication.


Channels Property

Returns a Channels collection object.

Syntax

NSChannelMgr.Channels

Example

NSChannelMgr.Connect "LocalHost"
Dim MyStations
Set MyStations = NSChannelMgr.Channels
MsgBox "There are " & MyStations.Count & " Station objects"
MyStations(0).Close  'remove a Station
Set MyStations = NSChannelMgr. Channels ' update collection

Remarks

If you remove a Channel object from the collection, you must retrieve a new collection. In Visual Basic this is done by reissuing the Set statement again to update the collection object.

See Also

Station Manager Properties


Clients Property

Returns a Clients collection object.

Syntax

NSChannelMgr.Clients

Example

NSChannelMgr.Connect "LocalHost"
Dim MyClients
Set MyClients = NSChannelMgr.Clients
MsgBox "There are " & MyClients.Count & " Client objects"
MyClients(0).Close  'remove a Client
Set MyClients = NSChannelMgr.Clients ' update collection

Remarks

If you remove a Client object from the collection, you must retrieve a new collection. In Visual Basic this is done by reissuing the Set statement again to update the collection object.

See Also

Station Manager Properties


EnableHttpStreaming

EnableHttpStreaming Property

Returns or sets a Boolean value specifying whether the NetShow Station Manager Control will enable HTTP streaming. By default, this value is TRUE.

Syntax

NSUnicastMgr.EnableHttpStreaming

Example

Sub ToggleHttpStreaming
  ' Turns HTTP streaming on or off
   If NSChannelMgr.EnableHttpStreaming = True Then
      NSChannelMgr.EnableHttpStreaming = False
   Else
      NSChannelMgr.EnableHttpStreaming = True
   End If
   MsgBox( "HttpStreaming value: " & NSChannelMgr.EnableHttpStreaming)
End Sub


EnableProxy

EnableProxy Property

Returns or sets a Boolean value indicating whether connecting to a proxy server is enabled.

Syntax

NSUnicastMgr.EnableProxy

Remarks

NetShow supports HTTP stream distribution among NetShow servers. For example, the server connected to this instance of the Station Manager control could be distributing streams to multiple downstream servers. It may try, using HTTP, to connect to a server behind a firewall. This property is used to set or return a value that determines whether or not this server can connect to a proxy server.


HostAddresses Property

Returns a HostAddresses collection object.

Syntax

NSChannelMgr.HostAddresses

Example

NSChannelMgr.Connect "LocalHost"
Dim Addresses
Set Addresses = NSChannelMgr.HostAddresses
MsgBox "There are " & Addresses.Count & " HostAddress objects"

See Also

Station Manager Properties


ProxyHostName

ProxyHostName Property

Returns or sets a String value specifying the proxy host name.

Syntax

NSChannelMgr.ProxyHostName

Remarks

NetShow supports HTTP stream distribution among NetShow servers. For example, the server connected to this instance of the Station Manager control could be distributing streams to multiple downstream servers. It may try, using HTTP, to connect to a server behind a firewall. This property returns the name of the proxy server to which this server is currently connected.


ProxyUser

ProxyUser Property

Returns a String value specifying the user ID that is used for proxy authentication.

Syntax

NSChannelMgr.ProxyUser

Remarks

NetShow supports HTTP stream distribution among NetShow servers. For example, the server connected to this instance of the Station Manager control could be distributing streams to multiple downstream servers. It may try, using HTTP, to connect to a server behind a firewall. This property returns the username used if this server is challenged by a proxy server.


Server Property

Returns the server name for the current connection.

Syntax

NSChannelMgr.Server

Example

NSChannelMgr.Connect "LocalHost"
MsgBox "Netshow running on server " & NSChannelMgr.Server

See Also

Station Manager Properties


Streams Property

Returns a Streams collection object.

Syntax

NSChannelMgr.Streams

Example

NSChannelMgr.Connect "LocalHost"
Dim MyStreams
Set MyStreams = NSChannelMgr.Streams
MsgBox "There are " & MyStreams.Count & " Stream objects"
MyStreams(0).Close  'remove a stream
Set MyStreams = NSChannelMgr.Streams ' update collection

Remarks

If you remove a Stream object from the collection, you must retrieve a new collection. In Visual Basic this is done by reissuing the Set statement again to update the collection object.

See Also

Station Manager Properties


Objects Managed by the Station Manager Control

The Station Manager Control manages the following objects:

Object | Description
Address | Contains information for each address.
Client | Contains information on each client.
Clients | Collection of Client objects.
Channel | Contains information for each channel.
ChannelFormats | Collection of ChannelFormat objects.
ChannelFormat | Contains format information for each channel.
Channels | Collection of Channel objects.
HostAddresses | Collection of Address objects.
StreamDescriptor | Contains stream information for each channel format.
StreamDescriptors | Collection of StreamDescriptor objects.
Stream | Contains information for each stream.
Streams | Collection of Stream objects.


Channels Object

The Channels collection object is a collection of Channel objects.

The Channels collection object has the following methods:

Methods | Description
Open | Opens a Channel object.
Find | Searches for the specified Channel object.

The Channels collection object has the following properties:

Properties | Read/Write | Description
Item | R | Returns the specified Channel object.
Count | R | Returns the number of Channel objects.


Channels.Find

Channels.Find Method

Finds a Channel object with a specific name.

Syntax

NSChannelMgr.Channels.Find( StationName )

Parameters

StationName

A String value specifying the name of the station to be found.

Return Values

Returns a Channel object.

Example

NSChannelMgr.Connect "LocalHost"
' find Station named OHlive
Set AStation = NSChannelMgr.Channels.Find( "OHlive")
' give it a description
AStation.Description = "Live rex from Opera House"

See Also

Channels object


Channels.Open Method

Opens a Channel object.

Syntax

NSChannelMgr.Channels.Open( StationName, PeerAccess )

Parameters

StationName

A String value specifying the name of the station to be opened.

PeerAccess

The peer access of the station. The values may be combined.

Value | Description
1 | Read
2 | Write
4 | Delete
7 | All

Return Values

Returns a Channel object.

Example

NSChannelMgr.Connect "LocalHost"
Dim Stations
Set Stations = NSChannelMgr.Channels
' create station "OHlive", give other servers read-only access
Stations.Open "OHlive", 1

Remarks

The peer access determines what permissions other administrative clients have. For example, opening a stream with delete access allows other clients to delete the stream. These permissions are reset when the current connection is closed.

See Also

Channels object


Channels.Count Property

Returns the number of Channel objects in a Channels collection object.

Syntax

NSChannelMgr.Channels.Count

Example

NSChannelMgr.Connect "LocalHost"
Dim Stations
Set Stations = NSChannelMgr.Channels
For i = 0 to Stations.Count – 1
' display station number and name
   MsgBox "Station " & Stations.Count " : " & _
          Stations(i).Name
Next i

See Also

Channels.Item, Channels object


Channels.Item Property

Returns the Channel object as specified by the Index value.

Syntax

NSChannelMgr.Channels.Item( Index )

Example

NSChannelMgr.Connect "LocalHost"
Dim Stations
Set Stations = NSChannelMgr.Channels
LastStation = Stations.Item( Stations.Count - 1 )
FirstStation = Stations.Item( 0 )
' using alternate syntax
AlsoTheFirstStation = Stations(0)

Remarks

The Item property is the default property. See the alternate syntax line in the example to see how it can be omitted.

See Also

Channels.Count, Channels object


Channel Objects

Channel objects are responsible for multicasting the content defined by stream objects.

Use the Channel object methods to create and close a station, and to associate streams with the station. and Channel object properties


Channel Object Methods

The Channel object contains the following methods for each station:

Method | Description
Close | Closes a station.
DistributeFrom | Expedites setting up distribution of content from a remote multicast manager.
GetActiveStream | Gets an active Stream object.
GetID | Gets a station ID.
InitializeFromNSC | Initializes the station from an .nsc file.
SetActiveStream | Assigns a Stream object to a station.
WriteNSC | Writes station information to an .nsc file.


Channel.Close Method

Closes a station.

Syntax

NSChannelMgr.Channels(ChannelName).Close

Return Values

Returns an ActiveX HRESULT error code.

Remarks

If you remove an item from the Channels collection object by using Close, you must use the Set statement again to refresh the object.

Example

Dim Stations
Set Stations = NSChannelMgr.Channels
Stations.Open "Station 1", 1  'give read access
Stations.Open "Station 2", 2  'give write access
Stations.Open "Station 3", 7  'give full access
Stations(1).Close     'close Station 2
' now set the collection again!
Set Stations = NSChannelMgr.Channels

See Also

GetID, GetActiveStream, SetActiveStream, InitializeFromNSC, WriteNSC, DistributeFrom


Channel.DistributeFrom Method

Expedites setting up distribution of content from a remote multicast manager.

Syntax

nsChannelMgr.Channels(ChannelName).DistributeFrom( Server, ChName, Filter )

Parameters

Server

A String value specifying the name of the remote multicast manager server.

ChName

A String value specifying the name of the station whose information is being imported.

Filter

The filter value indicates specific types of information to exclude. Filter values can be added together to exclude multiple types of information.

Return Values

Returns an ActiveX HRESULT error code.

Remarks

The DistributeFrom method imports all of the station information from a specific station on a remote server to the current server. This information can be used to configure the current server to multicast the stream by changing the IP address and port.

The filter is an enumeration of MCMDELIVERYMODE type, and can have the following values:

Value | Mnemonic | Description
1 | MCM_DM_SESSION | Ignore multicast address.
2 | MCM_DM_SESSIONLESS_3PH | Ignore multicast adapter address.
4 | MCM_DM_SESSIONLESS_EC | Ignore auto-archive directory.
8 | MCM_DM_DISTRIBUTION | Ignore station name.

Example

' pick up multicast distribution described in LiveShow on server
' "NSServer" but don't archive it in the same place
NSChannelMgr.Channels(1).DistributeFrom ("NSServer", "LiveShow.nsc",
   _4MCM_DM_SESSIONLESS_EC)

See Also

GetID, GetActiveStream, SetActiveStream, InitializeFromNSC, WriteNSC, Close


Channel.GetActiveStream Method

Gets an active Stream object.

Syntax

NSChannelMgr.Channels(ChannelName).GetActiveStream

Return Values

Returns the active Stream object.

Example

Set MyStation = NSChannelMgr.Channels.Find( "My Channel")
If MyStation.GetActiveStream.Name = MonoStream Then
   MyStation.SetActiveStream StereoStream
End If

See Also

GetID, GetActiveStream, SetActiveStream, InitializeFromNSC, WriteNSC, Close, DistributeFrom


Channel.GetID Method

Gets a station ID.

Syntax

NSChannelMgr.Channels(ChannelName).GetID

Return Values

Returns a Long value that represents a station ID.

Remarks

Station IDs are primarily used internally by NetShow.

See Also

GetActiveStream, SetActiveStream, InitializeFromNSC, WriteNSC, Close, DistributeFrom


Channel.InitializeFromNSC Method

Initializes the station from a .nsc file.

Syntax

NSChannelMgr.Channels(ChannelName).InitializeFromNSC( NSCFileName, Filter )

Parameters

NSCFileName

A String value specifying the name of the .nsc file containing information on the station being initialized.

Filter

The filter value indicates specific types of information to exclude. Filter values can be added together to exclude multiple types of information.

Return Values

Returns an ActiveX HRESULT error code.

Remarks

The filter is an enumeration of MCMDELIVERYMODE type, and can have the following values:

Value | Mnemonic | Description
1 | MCM_DM_SESSION | Ignore multicast address.
2 | MCM_DM_SESSIONLESS_3PH | Ignore multicast adapter address.
4 | MCM_DM_SESSIONLESS_EC | Ignore auto-archive directory.
8 | MCM_DM_DISTRIBUTION | Ignore station name.

Example

' Set a station to the properties defined in the NSC file "LASCALA" _
  but don't archive it in the same place
NSChannelMgr.Channel.DistributeFrom( "OHLive", MCM_DM_SESSIONLESS_EC )

See Also

GetID, GetActiveStream, SetActiveStream, InitializeFromNSC, WriteNSC, Close, DistributeFrom


Channel.SetActiveStream Method

Assigns a Stream object to a station.

Syntax

NSChannelMgr.Channels(ChannelName).SetActiveStream( Stream )

Parameters

Stream

A Stream object.

Return Values

Returns a station ID.

Example

Set MyStation = NSChannelMgr.Channels.Find( "My Channel")
If MyStation.GetActiveStream.Name = MonoStream Then
   MyStation.SetActiveStream StereoStream
End If

See Also

GetID, GetActiveStream, InitializeFromNSC, WriteNSC, Close, DistributeFrom


Channel.WriteNSC Method

Writes station information to an .nsc file.

Syntax

NSChannelMgr.Channels(ChannelName).WriteNSC( FileName, Overwrite )

Parameters

FileName

A String value specifying the file name, including the path, or UNC. The filename must have an .nsc extension.

Overwrite

Boolean flag indicating whether or not the file can overwrite a file of the same name. TRUE indicates that the file can be overwritten.

Return Values

Returns an ActiveX HRESULT error code.

Example

' Write (or overwrite) an NSC station information file
' called OHLive.NSC.
NSChannelMgr.Channel.WriteNSC( "c:\public\OHLive.nsc", TRUE )
NSChannelMgr.Channel.WriteNSC( "\\astrid\public\OHlive.nsc", TRUE )

See Also

GetID, GetActiveStream, InitializeFromNSC, Close, DistributeFrom


Channel Object Properties

The Channel object contains the following properties for each station:

Property | Read/Write | Description
AutoArchive | RW | Returns or sets a Boolean value that determines whether or not content is automatically cached.
AutoArchiveDir | RW | Returns or sets the String value containing the directory where the automatic content cache is stored.
AutoArchiveSize | RW | Returns or sets the Long value of the size in bytes of the automatic content cache.
ChannelFormats | R | Returns a ChannelFormats collection object.
ContactAddress | RW | Returns or sets the contact (mailing) address of the station.
ContactEmail | RW | Returns or sets the e-mail contact value of the station.
ContactPhone | RW | Returns or sets the contact phone number of the station.
DeliveryMode | RW | Returns or sets the delivery mode of the station.
Description | RW | Returns or sets the description of the station.
MulticastAddress | RW | Returns or sets the multicast address of the station.
MulticastAdapterAddress | RW | Returns or sets the address of the network adapter card used by the station.
MulticastTimeToLive | RW | Returns or sets the multicast time-to-live (TTL) value of the station.
Name | RW | Returns or sets the name of the station.
NSCURL | RW | Returns or sets the .nsc file URL of the station.
Port | RW | Returns or sets the port of the station.
Version | RW | Returns the version of the station.
DistributionLimit | RW | Returns or sets the maximum number of distribution points.
LogURL | RW | Returns or sets the URL of the server log file.
UnicastURL | RW | Returns or sets the URL of the Unicast publishing point.


Channel.AutoArchive Property

Returns or sets a Boolean value that determines whether or not content is automatically cached.

Syntax

Station.AutoArchive

Example

Set MyStation = NSChannelMgr.Channels.Find( "My Station")
If MyStation.AutoArchive Then
    MsgBox "Archive directory is " & MyStation.AutoArchiveDir _
            " with maximum size " & MyStation.AutoArchiveSize
  Else
    MsgBox "Station will not be archived"
End If

See Also

Channel object, Channel.AutoArchiveSize, Channel.AutoArchiveDir


Channel.AutoArchiveDir Property

Returns or sets the String value containing the directory where the automatic content cache is stored.

Syntax

Station.AutoArchiveDir

Example

Set MyStation = NSChannelMgr.Channels.Find( "My Station")
If MyStation.AutoArchive Then
    MsgBox "Archive directory is " & MyStation.AutoArchiveDir _
            " with maximum size " & MyStation.AutoArchiveSize
  Else
    MsgBox "Station will not be archived"
End If

Remarks

You must create the directory before archiving a station. Microsoft® NetShow™ will check to see if the directory exists before archiving.

See Also

Channel object, Channel.AutoArchiveSize, Channel.AutoArchiveDir


Channel.AutoArchiveSize Property

Returns or sets the Long value of the size in bytes of the automatic content cache.

Syntax

Station.AutoArchiveSize

Example

Set MyStation = NSChannelMgr.Channels.Find( "My Station" )
If MyStation.AutoArchive Then
    MsgBox "Archive directory is " & MyStation.AutoArchiveDir _
           " with maximum size " & MyStation.AutoArchiveSize
  Else
    MsgBox "Station will not be archived"
End If

See Also

Channel object, Channel.AutoArchiveDir, Channel.AutoArchive


Channel.ChannelFormats Property

Returns a ChannelFormats collection object.

Syntax

Station.ChannelFormats

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
' get the station formats
Set MyFormats = MyStation.ChannelFormats

See Also

ChannelFormats, Channel object, Channel.AutoArchive, Channel.AutoArchiveDir


Channel.ContactAddress Property

Returns or sets the contact (mailing) address of the station.

Syntax

Station.ContactAddress

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
MyStation.ContactAddress = "123 Varnay St., Megaville WA 98000"
MsgBox "Contact is: " & MyStation.ContactAddress

See Also

Channel object, ContactEmail, Channel.ContactPhone


Channel.ContactEmail Property

Returns or sets the e-mail contact value of the station.

Syntax

Station.ContactEmail

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
MyStation.ContactEmail = "astrid@opera.org"
MsgBox "Email Contact is: " & MyStation.ContactEmail

See Also

Channel object, Channel.ContactAddress, Channel.ContactPhone


Channel.ContactPhone Property

Returns or sets the contact phone number of the station.

Syntax

Station.ContactPhone

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
MyStation.ContactPhone = "1-206-555-1212"
MsgBox "Phone: " & MyStation.ContactPhone

See Also

Channel object, Channel.ContactAddress, Channel.ContactEmail


Channel.DeliveryMode Property

Returns or sets the delivery mode of the station.

Syntax

Station.DeliveryMode

Remarks

The delivery mode is an enumeration of type MCMDELIVERYMODE, and can have the following values:

Value | Mnemonic | Description
2 | MCM_DM_SESSIONLESS_3PH | Sessionless: data streamed via multicast with headers transferred to clients by some mechanism external to MCM
8 | MCM_DM_DISTRIBUTION | Distribution: data streamed via a point to point TCP connection
10 |  | Both Sessionless and Distribution modes are used

Example

Set MyStation = NSChannelMgr.Channels.Find( "Interviews")
Select Case MyStation.DeliveryMode
   Case 2 MsgBox "Station delivered by sessionless communication"
   Case 8 MsgBox "Station delivered by distribution"
End Select

See Also

Channel object, Channel.ChannelFormats, Channel.UnicastURL, Channel.NSCURL


Channel.Description Property

Returns or sets the String value for the description of the station.

Syntax

Station.Description

Example

Set MyStation = NSChannelMgr.Channels.Find( "Unrealistic Hi-fi")
MsgBox MyStation.Description = "Quadraphonic Surround-Sound!"

See Also

Channel object


Channel.LogURL Property

Returns or sets a String value specifying the server’s log URL.

Syntax

Station.LogURL

Remarks

The Media Player logs stream data to an HTTP server via an Internet Server API (ISAPI) DLL or Common Gateway Interface (CGI) script. This property specifies the HTTP URL containing the ISAPI or CGI logging script.


Channel.UnicastURL Property

Returns or sets a String value specifying the URL of the Unicast publishing point.

Syntax

Station.UnicastURL

Remarks

A unicast URL can be specified so that clients unable to receive a multicast can rollover to a unicast. The unicast URL is a text string that uses the following formats:

  • mms://<servername>/<virtualroot>
  • http://<servername>/<virtualroot>

Where the <virtualroot> is the alias for the publishing point and path of the station. This could be an .asf file on a server, or a stream from an encoder, such as:

msbd:\\<server>\<stationname>

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
' specify unicast rollover location
MyStation.UnicastURL = "mms://www.opera.org/bottesini"

See Also

Channel object, Channel.AutoArchive, Channel.AutoArchiveDir


Channel.DistributionLimit Property

Returns or sets a Long value of the maximum number of distribution points.

Syntax

Station.DistributionLimit


Channel.MulticastAddress Property

Returns or sets the String value for the multicast address of the station.

Remarks

The IP address used for a multicast should fall within the range from 224.0.0.0 through 239.255.255.255. Addresses in the 239.*.*.* range are recommended for intranets. Addresses in the 224.*.*.* range should be avoided, because they are reserved for low-level protocols. You can create multiple programs destined for the same IP address; however, you should avoid simultaneously multicasting programs to the same IP address.

Syntax

Station.MulticastAddress

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
MyStation.MulticastAddress = "239.2.254.100"
MsgBox "MyStation address: " & MyStation.MulticastAddress

See Also

Channel object, Channel.Port, Channel.MulticastAdapterAddress


Channel.MulticastAdapterAddress Property

Returns or sets the address of the network adapter card used by the station.

Syntax

Station.MulticastAdapterAddress

Remarks

If the multicast server has one network adapter (NIC), set the value to an empty string (""). If the server has multiple network adapters, specify the adapter by its IP address.

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
' set value to the default NIC
MyStation.MulticastAdapterAddress = ""
' set value to the IP address of the second NIC
MyStation.MulticastAdapterAddress = "121.5.24.9"

See Also

Channel object, MulticastAddress


Channel.MulticastTimeToLive Property

Returns or sets the multicast time-to-live (TTL) value of the station.

Syntax

Station.MulticastTimeToLive

Remarks

The TTL value determines the maximum number of times a multicast may be forwarded by routers as it passes along a network. This is called the scope of the multicast. At each hop along the route, the router decrements the TTL. When the value reaches 1, the next router will not forward the multicast.

Allowable values range from 1 through 255. Chose the value 1 to limit the multicast to your immediate subnet. To find the optimum value to limit a multicast to intranet multicast, you may need to consult your network administrator. The following values are suggested:

Option | Value
Local Network | 1
Intranet | 32
Internet | 128

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
MyStation.MulticastTimeToLive = 32
MsgBox "Multicast will pass through up to " & _
        MyStation.MulticastTimeToLive & " subnets"

See Also

Channel object


Channel.Name Property

Returns or sets the String value for the name of the station.

Syntax

Station.Name

Example

' change the station called mono to stereo
Set MyStation = NSChannelMgr.Channels.Find( "mono" )
MyStation.Name = "stereo"

See Also

Channel object, Channel.Channel.Description


Channel.NSCURL Property

Returns or sets the .nsc file URL of the station. The .nsc file is the NetShow station format file that is referred to by an .asx file.

Syntax

Station.NSCURL

Remarks

The .nsc file is only required for use with the NetShow Program Manager.

The .nsc file URL is a text string that uses the following formats:

  • http://<servername>/<filename>
  • \\<servername>\<share>\<filename>

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Find( "January Programs" )
' specify location for station NSC file
MyStation.NSCURL = "http://www.opera.org/janprog.nsc"

See Also

Channel object, Port  , MulticastAddress, ChannelFormats


Channel.Port Property

Returns or sets the port of the station.

IP port numbers range from 1 through 65535. Ports in the 32000 through 65000 range are recommended.

Syntax

Station.Port

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
MyStation.Port = 64288
MsgBox "MyStation address: " & MyStation.Port

See Also

Channel object, MulticastAddress, MulticastAdapterAddress


Channel.Version Property

Returns the version of the station.

Syntax

Station.Version

Remarks

The version of a station is incremented every time a property of the station changes.

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
MsgBox "Version: " & MyStation.Version

See Also

Channel object


ChannelFormats Collection Object Reference

The ChannelFormats collection object is a collection of ChannelFormat objects.

The ChannelFormats collection object has the following method:

Methods | Description
Add | Adds a ChannelFormat object to a Channel object.

The ChannelFormats collection object has the following properties:

Properties | Read/Write | Description
Item | R | Returns the specified ChannelFormat object.
Count | R | Returns the number of ChannelFormat objects.


ChannelFormats.Add Method

Adds a ChannelFormat object to a Channel object.

Syntax

Station.ChannelFormats.Add( StationFileName, FormatType )

Parameters

StationFileName

A String value specifying the file name of the station format to be added.

FormatType

The type of the station format to be added.

Return Values

Returns an ActiveX HRESULT error code.

Remarks

The station format is an enumeration of type MCMCHFORMATTYPE, has the following values:

Value | Mnemonic | Description
0 | MCM_INVALID_CH_FORMAT | Invalid
1 | MCM_ASD_CH_FORMAT_FILE | .asd File
2 | MCM_NSC_CH_FORMAT_FILE | .nsc File
3 | MCM_ASF_CH_FORMAT_FILE | .asf File

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
' add a new format described in an NSC file
MyStation.ChannelFormats.Add "c:\liveshow.nsc" MCM_NSC_CH_FORMAT_FILE

See Also

ChannelFormats collections, ChannelFormats objects


ChannelFormats.Count Property

Returns the number of ChannelFormat objects in a ChannelFormats collection object.

Syntax

Station.ChannelFormats.Count

Example

Set MyStation = NSChannelMgr.Channels.Item(1)
MsgBox "There are " & MyStation.ChannelFormats.Count & " formats"

NSChannelMgr.Connect "LocalHost"
Dim Formats
Set Formats = NSChannelMgr.ChannelFormats
BitrateTotal = 0
For i = 0 to Formats.Count – 1
   BitrateTotal = BitrateTotal + Formats(i).BitRate
Next i
MsgBox "Average bitrate for station formats is " _
       & BitrateTotal / Formats.Count

See Also

ChannelFormats collections, ChannelFormats objects, ChannelFormats.Item


ChannelFormats.Item Property

Returns the ChannelFormat object as specified by the Index value.

Syntax

Station.ChannelFormats.Item( Index )

Example

' get the second station in the collection
Set MyStation = NSChannelMgr.Channels.Item(1)
' get the first station format in the second station
Set MyFormat = MyStation.ChannelFormats.Item(0)

Remarks

The Item property is the default property for this object.

See Also

ChannelFormats collections, ChannelFormats objects, ChannelFormats.Count


ChannelFormat Objects

ChannelFormat objects define the physical characteristics of a multicast.

Use the ChannelFormat object methods to create and close a ChannelFormats object, and to associate streams with the station, and Channel object properties


ChannelFormat Method Reference

The ChannelFormat object contains the following methods for each station format:

Methods | Description
GetDescription | Returns a description of a station format.
GetKey | Returns a unique channel format key.
Remove | Removes a station format.


ChannelFormat.GetDescription Method

Gets a station format description.

Syntax

Station.ChannelFormats(index).GetDescription

Return Values

Returns a station format description.

Example

Set MyStation = NSChannelMgr.Channels.Item(0)
Set MyFormat = MyStation.ChannelFormats.Item(1)
MsgBox "Second station format description: " & _
    MyFormat.ChannelFormats.GetDescription

See Also

ChannelFormats objects


ChannelFormat.GetKey Method

Gets a unique channel format key.

Syntax

Station.ChannelFormats(index).GetKey

Return Values

Returns a Long value representing the key.


ChannelFormat.Remove Method

Removes a station format.

Syntax

Station.ChannelFormats(index).Remove

Return Values

Returns an ActiveX HRESULT error code.

Remarks

If you remove an item from the ChannelFormats collection by using the Remove method, you must use the Set method again to refresh the object.

Example

Set MyStation = NSChannelMgr.Channels.Item(1)
Set MyFormat = MyStation.ChannelFormats.Item(0)
' remove first format from second station
MyFormat.ChannelFormat.Remove
' refresh the ChannelFormats collection after removing format
Set MyFormat = MyStation.Channels.Item(0)

See Also

ChannelFormats objects


ChannelFormat Properties Reference

The ChannelFormat object contains the following properties for each station format:

Property | Read/Write | Description
BitRate | R | Returns the bit rate of the station format.
PacketSize | R | Returns the packet size of the station format.
StreamDescriptors | R | Returns a StreamDescriptors collection object.


ChannelFormat.BitRate Property

Returns the bit rate of the station format in bits per second.

Syntax

Station.ChannelFormats(index).BitRate

Example

Set MyStation = NSChannelMgr.Channels.Item(0)
Set MyFormat = MyStation.ChannelFormats.Item(1)
MsgBox "Bit rate of second format of first station's: " & _
    MyFormat.ChannelFormats.BitRate

See Also

ChannelFormats objects, ChannelFormat.PacketSize


ChannelFormat.PacketSize Property

Returns the packet size of the station format.

Syntax

Station.ChannelFormats(index).PacketSize

Example

Set MyStation = NSChannelMgr.Channels.Item(0)
Set MyFormat = MyStation.ChannelFormats.Item(1)
MsgBox "Packet size of second format of first station's: " & _
    MyFormat.ChannelFormats.PacketSize

See Also

ChannelFormats objects, ChannelFormat.BitRate


ChannelFormat.StreamDescriptors Property

Returns a StreamDescriptors collection object.

Syntax

Station.ChannelFormats(index).StreamDescriptors

Example

Set MyStation = NSChannelMgr.Channels.Item(0)
Set MyFormat = MyStation.ChannelFormats.Item(0)
' initialize collection of descriptors in first
' format of first station
Set MyDescriptors = MyFormat.StreamDescriptors

Remarks

StreamDescriptor objects are used to contain information about streams, such as the width and height of the size of images or video, and types of media.

See Also

ChannelFormat objects, StreamDescriptor objects


StreamDescriptors Collection Object Reference

The StreamDescriptors collection object is a collection of StreamDescriptor objects.

StreamDescriptor objects are used to contain information about streams, such as the width and height of the size of images or video, and types of media.

The StreamDescriptors collection object has the following properties:

Properties | Read/Write | Description
Count | R | Returns the number of StreamDescriptor objects.
Item | R | Returns a specified StreamDescriptor object.

See Also

StreamDescriptor objects


StreamDescriptors.Count Property

Returns the number of StreamDescriptor objects in a StreamDescriptors collection object.

Syntax

StationFormat.StreamDescriptors.Count

Example

Set MyStation = NSChannelMgr.Channels.Item(0)
Set MyFormat = MyStation.ChannelFormats.Item(0)
MsgBox MyFormat.StreamDescriptors.Count & _
   " descriptors in collection"

See Also

StreamDescriptors collection, StreamDescriptor objects, StreamDescriptors.Item


StreamDescriptors.Item Property

Returns the StreamDescriptor object as specified by the Index value.

Syntax

StationFormat.StreamDescriptors.Item( Index )

Example

Set Station1 = NSChannelMgr.Channels.Item(0)
Set Format2 = Station1.ChannelFormats(1)
' two forms for syntax to obtain object
Set Descriptor1 = Format2.StreamDescriptors.Item(0)
Set Descriptor2 = Format2.StreamDescriptors(1)

Remarks

The Item property is the default property for this object.

See Also

StreamDescriptors collection, StreamDescriptor objects, StreamDescriptors.Count


StreamDescriptor Object Reference

The StreamDescriptor object contains methods and properties for each stream descriptor format.

The StreamDescriptor object has the following properties:

Property | Read/Write | Description
Description | R | Returns the description of the StreamDescriptor object.
Height | R | Returns the height value of the StreamDescriptor object.
Type | R | Returns the type of StreamDescriptor object.
Width | R | Returns the width value of the StreamDescriptor object.

See Also

StreamDescriptors collection object


StreamDescriptor.Description Property

Returns the description of the StreamDescriptor object.

Syntax

ChannelFormat.StreamDescriptor.Description

Example

Set Station1 = NSChannelMgr.Channels(0)
Set Format1 = Station1.ChannelFormats(0)
MsgBox "Describing descriptor description:" _
    Format1.StreamDescriptors.Description

See Also

StreamDescriptors collection object, StreamDescriptor objects, StreamDescriptor.Height, StreamDescriptor.Width, StreamDescriptor.Type


StreamDescriptor.Height Property

Returns the height value of the StreamDescriptor object.

Syntax

StationFormat.StreamDescriptors(index).Height

Remarks

This property returns an error if the stream descriptor description is not Video or Image.

Example

Set Station1 = NSChannelMgr.Channels(0)
Set Format1 = Station1.ChannelFormats(0)
MsgBox "stream height is:" _
    Format1.StreamDescriptors(0).Height

See Also

StreamDescriptors collection, StreamDescriptor objects, StreamDescriptor.Width, StreamDescriptor.Type, StreamDescriptor.Description


StreamDescriptor.Type Property

Returns the type of StreamDescriptor object.

Syntax

StationFormat.StreamDescriptors(index).Type

Remarks

Stream descriptors are an enumeration of type MCMSTREAMTYPE, and have the following type values:

Value | Mnemonic | Description
0 | MCM_INVALID_STREAM | Invalid. The stream descriptor cannot be initialized.
1 | MCM_AUDIO_STREAM | Audio
2 | MCM_VIDEO_STREAM | Video
3 | MCM_IMAGE_STREAM | Image
4 | MCM_SCRIPT_STREAM | Script
5 | MCM_UNKNOWN_STREAM | Unknown

Example

Set Station1 = NSChannelMgr.Channels.Item(0)
Set Format4 = MyStation.ChannelFormats.Item(3)
Select Case Format4.StreamDescriptors(0).Type
  Case 0 MsgBox "descriptor type invalid"
  Case 1 MsgBox "Audio descriptor type"
  Case 2 MsgBox "Video descriptor type"
  Case 3 MsgBox "Image descriptor type"
  Case 4 MsgBox "Script descriptor type"
  Case 5 MsgBox "Unknown descriptor type"
End Select

See Also

StreamDescriptors collection, StreamDescriptor objects, StreamDescriptor.Width, StreamDescriptor.Description, StreamDescriptor.Height


StreamDescriptor.Width Property

Returns the width value of the StreamDescriptor object.

Syntax

StationFormat.StreamDescriptors(index).Width

Remarks

This property returns an error if the stream descriptor description is not Video or Image.

Example

Set Station1 = NSChannelMgr.Channels(0)
Set Format1 = Station1.ChannelFormats(0)
MsgBox "stream width is:" _
    Format1.StreamDescriptors(0).Width

See Also

StreamDescriptors collection, StreamDescriptor objects, StreamDescriptor.Description, StreamDescriptor.Height, StreamDescriptor.Type


Streams Collection Object Reference

The Streams collection object is a collection of Stream objects.

The Streams collection object has the following methods:

Method | Description
Open | Opens a Stream object.
Find | Finds a specified Stream object.

The Streams collection object has the following properties:

Properties | Read/Write | Description
Item | R | Returns a specified Stream object.
Count | R | Returns the number of Stream objects.

See Also

Stream objects


Streams.Find Method

Finds a Stream object with a specific name.

Syntax

NSChannelMgr.Streams.Find( Alias )

Parameters

Alias

A String value specifying the alias for a name of the stream to be found.

Return Values

Returns a Stream object.

Example

NSChannelMgr.Connect "LocalHost"
' find Stream named Product Rollout
Set RolloutStream = NSChannelMgr.Streams.Find( "Product Rollout")

See Also

Streams collection object, Stream objects, Streams.Open


Streams.Open Method

Opens a Stream object.

Syntax

NSChannelMgr.Streams.Open( StreamSource, Alias, PeerAccess )

Parameters

StreamSource

A String value specifying the name of the stream source to be opened.

Alias

A String value specifying the alias for a name of the stream source to be opened. This can be an .asf file distributed via the mms: or http: protocols, or a stream from an encoder distributed via the msdb: protocol.

PeerAccess

The peer access of the stream. The values may be combined.

Value | Mnemonic | Description
1 | MCM_PA_READ | Read
2 | MCM_PA_WRITE | Write
4 | MCM_PA_DELETE | Delete
7 | MCM_PA_ALL_ACCESS | All

Example

NSChannelMgr.Connect "LocalHost"
MCM.Channels.Open( "MyStation", MCM_PA_ALL_ACCESS )
Dim MyStream
' open stream "Welcome" with read access
Set MyStream = MCM.Streams.Open ("mms://nsserver/welcome.asf", _
               "Welcome", MCM_PA_READ)
MyStation.SetActiveStream Welcome

Return Values

Returns a Stream object.

Remarks

The peer access determines what permissions other administrative clients have. For example, opening a stream with delete access allows other clients to delete the stream.

You must open a stream by using the Set statement.

See Also

Streams collection, Stream objects, Streams.Find


Streams.Count Property

Returns the number of Stream objects in a Streams collection object.

Syntax

NSChannelMgr.Streams.Count

Example

NSChannelMgr.Connect "LocalHost"
Dim Streams
Set Streams = NSChannelMgr.Streams
LastStream = Streams( Streams.Count – 1 )
MsgBox Streams.Count & " Streams in collection"

See Also

Streams collection, Stream objects, Streams.Item


Streams.Item Property

Returns the Stream object as specified by the Index value.

Syntax

NSChannelMgr.Streams.Item( Index )

Example

NSChannelMgr.Connect "LocalHost"
Dim Streams
Set Streams = NSChannelMgr.Streams
MsgBox Streams.Item(0).Title

See Also

Streams collection, Stream objects, Streams.Count


Stream Object Methods

The Stream object contains the following methods for each stream:

Method | Description
Close | Closes a stream.
GetChannel | Gets the station associated with a stream.
GetID | Returns a stream ID.
GetState | Gets the state of a stream object.
Start | Starts a stream.
Stop | Stops a stream.

See Also

Streams collection


Stream.Close Method

Closes a stream.

Syntax

NSChannelMgr.Streams(index).Close

Return Values

Returns an ActiveX HRESULT error code.

Remarks

If you remove an item from the Streams collection object by using the Close method, you must use the Set statement again to refresh the object.

Example

Dim Streams
Set Streams = NSChannelMgr.Streams
Stream1 = Streams(0)
' close first stream on server
Stream1.Close
' reinitialize streams collection
Set Streams = NSChannelMgr.Streams

See Also

Streams collection, Stream objects, Stream.Stop


Stream.GetChannel Method

Gets the Station object associated with a stream.

Syntax

NSChannelMgr.Streams(index).GetChannel

Return Values

Returns a stream Station object.

Example

Dim Streams
Set Streams = NSChannelMgr.Streams
Set Station1 = Stream(0).GetChannel

See Also

Streams collection, Stream objects, Stream.GetID, Stream.GetState


Stream.GetID Method

Gets a stream ID, in the form of a unique long integer.

Syntax

NSChannelMgr.Streams(index).GetID

Return Values

Returns a stream ID, as a Long value.

Example

Dim Streams
Set Streams = NSChannelMgr.Streams
Stream1 = Streams(0)
MsgBox "First stream ID: " & Stream1.GetID

Remarks

See Also

Streams collection, Stream objects, Stream.GetState, Stream.GetChannel


Stream.GetState Method

Gets the state of a Stream object.

Syntax

NSChannelMgr.Streams(index).GetState

Return Values

Returns the stream state.

Remarks

Stream states are defined in an enumeration of type MCMSTREAMSTATE. Valid values are:

Value | Mnemonic | Description
1 | MCM_SS_CLOSED | Closed
2 | MCM_SS_OPEN | Open
3 | MCM_SS_STREAMING | Streaming
4 | MCM_SS_RESTARTING | Restarting

Example

Dim Streams
Set Streams = NSChannelMgr.Streams
Select Case Stream(0).GetState
  Case 1 MsgBox Stream(0).Title & " is closed"
  Case 2 MsgBox Stream(0).Title & " is open"
  Case 3 MsgBox Stream(0).Title & " is streaming"
  Case 4 MsgBox Stream(0).Title & " is restarting"
End Select

See Also

Streams collection, Stream objects, Stream.GetChannel, Stream.GetID


Stream.Start Method

Starts a stream.

Syntax

NSChannelMgr.Streams(index).Start( StreamPosition )

Parameters

StreamPosition

A Long value indicating the position in the stream, in milliseconds.

Return Values

Returns an ActiveX HRESULT error code.

Remarks

A stream can start at an offset specified by the StreamPosition only if the Seekable property is set.

Example

MCM.Channels.Open( "MyStation", 7 )
Dim MyStream
' open stream "Welcome" with read access
Set MyStream = MCM.Streams.Open ("mms://nsserver/welcome.asf", _
               "Welcome", 1)
MyStation.SetActiveStream Welcome
If MyStream.Seekable Then
  MyStream.Start 5000 'skip first 5 seconds
Else
  MyStream.Start 0    'start at the beginning
End If

See Also

Streams collection, Stream objects, Stream.Stop, Stream.Close


Stream.Stop Method

Stops a stream.

Syntax

NSChannelMgr.Streams(index).Stop

Return Values

Returns an ActiveX HRESULT error code.

Example

Dim Streams
Set Streams = NSChannelMgr.Streams
' stop first stream on server
Stream(0).Stop

See Also

Streams collection, Stream objects, Stream.Close, Stream.Open, Stream.Start


Stream Object Properties Reference

The Stream object contains the following properties for each stream:

Property | Read/Write | Description
Alias | R | Returns the alias of a stream.
ArchiveFile | RW | Returns or sets the name of the archive file of a Stream object.
ArchiveSize | RW | Returns or sets the size of the archive file of a Streamobject.
ContentType | R | Returns the content type of the stream.
Description | RW | Returns or sets the description of a Streamobject.
Seekable | R | Returns a value determining whether or not the stream is seekable.
Source | R | Returns the source of the stream.
Title | RW | Returns or sets the title of a Streamobject.

See Also

Streams collection, Stream objects


Clients Collection Object Reference

The Clients collection object is a collection of Client objects. In this context, a client is another NetShow server that is connected for administrative purposes.

The Clients collection object has the following properties:

Property | Read/Write | Description
Item | R | Returns a specified Client object.
Count | R | Returns the number of Client objects.


Clients.Count Property

Returns the number of objects in a Count collection object.

Syntax

NSChannelMgr.Clients.Count

Example

NSChannelMgr.Connect "LocalHost"
Dim Clients
Set Clients = NSChannelMgr.Clients
MsgBox Clients.Count & " clients connected"

See Also

Clients.Item


Clients.Item Property

Returns the Count object as specified by the Index value.

Syntax

NSChannelMgr.Clients.Item( Index )

Example

NSChannelMgr.Connect "LocalHost"
Dim Clients
Set Clients = NSChannelMgr.Clients
MsgBox Clients.Item(0).Address

Remarks

The Item property is the default property for this object.

See Also

Clients.Count


Stream Objects

Stream objects are responsible for multicasting the content they define.

Use the Stream object methods to create, start, and stop streams, and to set the Stream object properties


Client Object Reference

The Client object contains methods and properties for each client.

The Client object has the following method:

  • Disconnect

The Client object has the following properties:

Property | Read/Write | Description
Address | R | Returns the address of the Client object.
ChannelID | R | Returns the station ID of the Client object.
DeliveryMode | R | Returns the delivery mode of the Client object.
Id | R | Returns the ID of the Client object.

See Also

Clients collection object


HostAddresses Collection Object Reference

The HostAddresses collection object is a collection of Address objects.

The HostAddresses collection object has the following properties:

Property | Read/Write | Description
Item | R | Returns a specified Address object.
Count | R | Returns the number of Address objects.

See Also

Address objects


HostAddresses.Count Property

Returns the number of Address objects in a HostAddresses collection object.

Syntax

NSChannelMgr.HostAddresses.Count

Example

NSChannelMgr.Connect "LocalHost"
Dim Hosts
Set Hosts = NSChannelMgr.HostAddresses
' write a list of addresses and properties
For i = 0 to Hosts.Count - 1
   str = "<B>Host #" & i & "</B><BR>"
   str = str + "Type: " & Hosts.Item(i).Type & "<BR>"
   str = str + "Port: " & Hosts.Item(i).Port & "<BR>"
   str = str + "Address: " & Hosts.Item(i).Address & "<BR><BR>"
Document.Write str
Next i

See Also

HostAddresses.Item, Address objects , HostAddresses collection


HostAddresses.Item Property

Returns the Address object as specified by the Index value.

Syntax

NSChannelMgr.HostAddresses[.Item]( Index )

Example

NSChannelMgr.Connect "LocalHost"
Dim Hosts
Set Hosts = NSChannelMgr.HostAddresses
' write a list of addresses and properties
For i = 0 to Hosts.Count - 1
   str = "<B>Host #" & i & "</B><BR>"
   str = str + "Type: " & Hosts.Item(i).Type & "<BR>"
   str = str + "Port: " & Hosts.Item(i).Port & "<BR>"
   str = str + "Address: " & Hosts.Item(i).Address & "<BR><BR>"
Document.Write str
Next i

Remarks

The Item property is the default property for this object.

See Also

HostAddresses.Count, Address objects , HostAddresses collection object


Address Object Reference

The Address object contains properties for each address.

The Address object has the following properties:

Property | Read/Write | Description
Address | R | Returns the address of the Address object.
Port | R | Returns the port of the Address object.
Type | R | Returns the Internet socket type of the Address object.


Address.Address Property

Returns the address of the Address object.

Syntax

NSChannelMgr.Address.Address

Example

NSChannelMgr.Connect "LocalHost"
Dim Hosts
Set Hosts = NSChannelMgr.HostAddresses
' write a list of addresses and properties
For i = 0 to Hosts.Count - 1
   str = "<B>Host #" & i & "</B><BR>"
   str = str + "Type: " & Hosts.Item(i).Type & "<BR>"
   str = str + "Port: " & Hosts.Item(i).Port & "<BR>"
   str = str + "Address: " & Hosts.Item(i).Address & "<BR><BR>"
Document.Write str
Next i

See Also

Address.Port, Address.Type, Address objects , HostAddresses collection object


Address.Port Property

Returns the port of the Address object.

Syntax

NSChannelMgr.Address.Port

Example

NSChannelMgr.Connect "LocalHost"
Dim Hosts
Set Hosts = NSChannelMgr.HostAddresses
' write a list of addresses and properties
For i = 0 to Hosts.Count - 1
   str = "<B>Host #" & i & "</B><BR>"
   str = str + "Type: " & Hosts.Item(i).Type & "<BR>"
   str = str + "Port: " & Hosts.Item(i).Port & "<BR>"
   str = str + "Address: " & Hosts.Item(i).Address & "<BR><BR>"
Document.Write str
Next i

See Also

Address.Type, Address.Address, Address objects , HostAddresses collection


Address.Type Property

Returns the Internet socket type of the Address object. The only type supported is type 4.

Syntax

NSChannelMgr.Address.Type

Example

NSChannelMgr.Connect "LocalHost"
Dim Hosts
Set Hosts = NSChannelMgr.HostAddresses
' write a list of addresses and properties
For i = 0 to Hosts.Count - 1
   str = "<B>Host #" & i & "</B><BR>"
   str = str + "Type: " & Hosts.Item(i).Type & "<BR>"
   str = str + "Port: " & Hosts.Item(i).Port & "<BR>"
   str = str + "Address: " & Hosts.Item(i).Address & "<BR><BR>"
Document.Write str
Next i

See Also

Address.Port, Address.Address, Address objects , HostAddresses collection object


Station Manager Samples

Simple_Example A simple example showing how to use the Station Manager Control to list stations.

To test the SDK sample, you should have the appropriate ActiveX controls installed in your system. It is recommended that you run these samples on a machine that has NetShow installed. To download the complete suite of NetShow products visit the NetShow web site http://www.microsoft.com/NetShow


NetShow Authentication API

[This is preliminary documentation and subject to change.]

The Microsoft® NetShow™ Authentication API is designed to provide the foundation for creating custom authentication plug-in components known as authenticators. This document first presents a brief introduction of authentication concept, and then explains how the NetShow server and the authenticators cooperate with each other. It also discusses what you need to do to write an authentication plug-in component. A detailed reference of the Authentication API follows at the end of this document.

The following table presents a summary of the subjects.

Subject | Description
About the NetShow Authentication API | General discussion of authentication and authentication types.
Using the NetShow Authentication API | Discussions of how to write custom authentication plug-in components and to perform system registration.
The NetShow Authentication API Reference | Detailed discussions of the API references, organized by interfaces.
NetShow Authentication API Sample | A sample component, written in C++, that illustrates how to develop NetShow authentication plug-in components.


About the NetShow Authentication API

Authentication involves user validation before any information exchange takes place. When a client initiates a request to the server that has authentication enabled, the server challenges the client to confirm its identity. Typically, this amounts to inspecting the name and password of the user account under various authentication protocols. However, both client and server must adhere to one agreed protocol.

The Microsoft NetShow Unicast Server Manager supports user authentication as a security feature to grant access to NetShow content. The NetShow server can be configured to have authentication enabled. The authentication is either offered as a built-in capability or enabled via a plug-in component.

With an authenticator, the server can delegate the responsibility of credential validation to a dedicated component. With the authenticator components, it is possible to implement authentication schemes of varied sophistication. The NetShow authenticators are COM-based objects. You can adopt custom authentication logic by creating an authentication plug-in component. Using the NetShow Authentication API, you can create an authenticator with ease and integrate it with the NetShow server seamlessly to check client credentials against any pre-installed or custom-made user account databases, and to notify the server of the outcome.

Each authenticator is designed to implement one type of authentication. Although there can be more than one authenticator registered in the system, only one authenticator can be used at a time.


Authentication Types

The authentication type describes the security protocol used to exchange authentication information between peers. The type is communicated to the client, providing it with the information needed to interpret and package the data exchanged with the server.

The NetShow server and player support two types of built-in authentication protocols:

  • HTTP-BASIC.

  • Microsoft Windows NT® LAN Manager (NTLM)

Both types of authentication check the client credentials against the appropriate database of user accounts. The NTLM protocol employs a challenge/response scheme based on the NTLM credentials stored in the NTLM database. HTTP-BASIC is a text-based protocol that transmits Uuencoded strings of user name and password over TCP/IP. The NTLM protocol is more secure, but the HTTP-BASIC protocol is better suited for distributed systems over the Internet. For more information, see the subjects titled as “NTLM Authentication Protocol” and “HTTP-BASIC Authentication Protocol” in this document.

Authenticators can use either protocol. However, because only one type of authenticator may be presented to the client, the type of the protocol must be determined before any authentication commences. Therefore, only one authenticator may be enabled at a time. Every time an authenticator, as either plug-in or built-in component, is enabled or disabled, the server must be restarted in order for the changes to take effect. Restarting the server breaks all client connections and clears any authentication in progress. When clients reconnect, they must be authenticated again by using the new authenticator.

HTTP-BASIC Authentication Protocol

HTTP-BASIC authentication takes place by using HTTP. The information exchanged is text-based data consisting of the user’s name and password. The client and server communicate over TCP/IP. This means that Basic authentication can take place between any client/server pair on the Internet, and will pass through proxy servers and firewalls.

Under the HTTP-BASIC protocol, the client receives an authentication error when it attempts to open a title. The player responds by displaying a user name and password dialog box. The server retrieves the user name and password (client credentials) and passes them to the authenticator as a base 64 uuencoded string. The authenticator then checks the string against the user account database and informs the server of the results. If the user account is in a different domain than the server, the user name should be in the form of domain\username.

The HTTP-BASIC authentication protocol is ideal for Internet applications. It is also easily adaptable for use with custom-built or preexisting user account databases. Authenticators can be designed to receive the client credentials and compare the password against any name space.

NTLM Authentication Protocol

When a client attempts to open a title and NTLM authentication is enabled, the NetShow server uses an encrypted challenge/response scheme to authenticate the user logged in to the current session on the client computer. Because NTLM uses authentication information established when the user logs on, it requires the client and server to be on the same or trusted domains. NTLM authentication is done without transfer user’s credentials, which means the NetShow server does not have access to the user name or password. NTLM authentication protocol is better suited for intranet applications.

The challenge/response of the NTLM authentication involves three pieces of data being exchanged.

  • When the client receives the authentication error, it responds by sending its domain and computer name to the server. The server passes this data to the authenticator.
  • The authenticator passes back the NTLM challenge, and the server sends this data to the client.
  • The client replies by sending the NTLM challenge response to the server. The server passes this data to the authenticator for inspection.

The authenticator checks the data against entries stored in the NTLM user account database and notifies the server of the result. The server grants or denies the client access to the content based on the result.


NetShow Authentication Interfaces

The NetShow Authentication API consists of three COM-compliant interfaces. The three interfaces specify how the server and authenticators cooperate with each other. The COM objects are responsible for instantiation and initialization of the authenticator, as well as maintenance of user connections and client validation. The authenticator must implement two of the interfaces for the server to invoke their methods. The server implements the remaining callback interface to be invoked by an authenticator. The following is a brief description of those interfaces:

Interface | Description
INSSAuthenticator | Used to perform initialization of the authenticator, create a user authentication object, and specify the type of authentication. This interface is implemented by the authenticator, and its methods are called by the server.
INSSUserAuthentication | Used to inspect authentication data passed from the client to the server. This interface also exposes methods necessary for the server to impersonate the client for authentication purposes. This interface is implemented by the authenticator, and its methods are called by the server.
INSSAuthenticationCallback | Used to inform the server of the results of the authentication process. This interface is implemented by the server, and its method is called by the authenticator.


Using the NetShow Authentication API

This section explains in details the interaction between the client, the NetShow server, and the authenticator.

Initialization

At startup the NetShow server queries the system registry for the enabled authenticator. When successful, it retrieves the CLSID of the authenticator and creates an instance of the authenticator. Then the server calls the authenticator’s Initialize method, passing in a pointer to the server context. This context contains properties describing certain attributes of the server. These properties include:

  • The server name and alias.
  • The version number of the server.

The Initialize method also provides an opportunity for the authenticator to perform any preliminary authentication tasks, such as establishing a link to the user account database and allocating system resources that will be used by the authenticator.

During initialization, the authenticator also informs the server whether data exchanged with the client during authentication should be text-based or in binary form.

User Authentication Object

A user authentication object, managed by the Authenticator object, inspects and verifies user information each time a user connects. The server calls the Authenticator’s CreateUserAuthentication method to create a user authentication object. Authentication for the instance of the client connection is done through the user authentication object.

Setting the Authentication Type

After creating the user authentication object, the server calls the GetAuthenticationType method to retrieve the authentication type being used by the authenticator. This type must be recognizable by the client (player). Currently, the player only supports the following authentication types:

  • HTTP-BASIC
  • NTLM

How Authentication works

Each time a client makes a request to open a title, the server notifies the player that user authentication is required. Regardless of which authentication type is being used, authentication involves the exchange of data between the client, the server, and the authenticator. The server requests data from the client, such as a user name and password, and passes them to the authenticator for inspection. The authenticator notifies the server through a callback method that the authentication is complete or that a further exchange of data is necessary to complete the authentication process. The exchange of data continues until either the authenticator notifies the server through the callback that authentication is complete or an error occurs. Theoretically, the data exchange can continue forever; however, most authentication schemes involve only one to three exchanges.

The NetShow player prompts the user for user name and password credentials and dispatches the credentials to the server. The server then passes them to the authenticator for inspection and validation. The authenticator, using any available user account database, compares the data and notifies the server of the result. The server then grants or denies the client access to the content based on the result.

The following chart depicts the interaction between the client, the server, and the authenticator using the HTTP-BASIC authentication protocol.

After Authentication

After the user’s identity has been validated, the server stores a pointer to the authentication context in the user authentication object. The INSSAuthentication interface provides methods for retrieving the results of authentication and the authenticated user name. When the authentication is successful, the NetShow server can then impersonate the user whenever it is needed.


NetShow Authentication API Reference

The authenticator’s methods for must be created and implemented according to the specifications detailed in this reference section.

All interfaces, whether implemented by the server or the developer, must be COM-compliant. They must inherit the Iunknown interface and implement the following methods, in addition to their own methods:

  • QueryInterface
  • AddRef
  • Release

All NetShow authenticators are free threaded objects. Free threaded objects are responsible for thread safe synchronization, because they may be called from several different threads at the same time.


INSSAuthenticationCallback

The INSSAuthenticationCallback interface exposes the following method:

Method | Description
OnAuthenticateComplete | Notifies the NetShow server of the results of authentication.

Remarks

This interface is implemented by the NetShow server.

See Also

INSSUserAuthentication, INSSAuthenticator


INSSAuthenticationCallback::OnAuthenticateComplete

The INSSAuthenticationCallback::OnAuthenticateComplete method is used to inform the server of the results of the authentication process.

Syntax

HRESULT OnAuthenticateComplete (
NS_AUTH_RESULT Result,
INSSUserAuthentication *pUserAuthentication,
DWORD dwRequestId
);

Parameters

[in] Result

Specifies the results of the authentication. Values supported for this parameter include:

Value | Description
NS_AUTH_SUCCESS | Informs the server that access rights have been granted to the client.
NS_AUTH_DENIED | Informs the server that access rights have been denied to the client.
NS_AUTH_CONTINUE | Informs the server that the authentication process is not complete and to request another blob of data.
NS_AUTH_ERROR | Informs the server that an error occurred during the authentication process.

[in] pUserAuthentication

Specifies a pointer to the client’s user-authentication object.

[in] dwRequestId

Specifies a unique identifier of the instance of the client connection. The request ID is passed to the INSSUserAuthentication::Authenticate method.

Return Values

This method should always return S_OK.

Remarks

If the result passed in to this method is NS_AUTH_CONTINUE, the server calls the INSSUserAuthentication::GetChallenge method to send additional data from the authenticator back to the client.

See Also

INSSUserAuthentication::Authenticate, INSSAuthenticator::CreateUserAuthentication


INSSAuthenticator

The INSSAuthenticator interface exposes the following methods;

Method | Description
CreateUserAuthentication | This method is called to create a user-authentication object for each instance of a client connection.
GetAuthenticatorClass | This method is called to retrieve the class ID of the authenticator.
GetAuthenticationType | This method is called to specify the authentication type.
Initialize | The server at the setup calls this method.

Remarks

This interface is implemented by the developer, and its methods are called by the NetShow server.

See Also

INSSUserAuthentication


INSSAuthenticator::CreateUserAuthentication

The INSSAuthenticator::CreateUserAuthentication method is used to create an uninitialized user-authentication connection object.

Syntax

HRESULT CreateUserAuthentication(
INSSUserAuthentication **ppUserCredential
);

Parameters

[out] ppUserCredential

Specifies the address of a pointer to the user-authentication object created.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

The NetShow server calls this method each time a client connects. All authentication performed for this instance of the client connection is done through this user-authentication object.

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CSampleAuthenticator::CreateUserAuthentication(
            INSSUserAuthentication **ppCtx )
{
  //
  // Create a new authentication context and initialize it.
  //
  CUserAuthentication * pContext = new CUserAuthentication();

  if( NULL == pContext )
  {
    return( E_OUTOFMEMORY );
  }
  HRESULT hr = pContext->Initialize( this );
  if( FAILED( hr ) )
  {
    delete pContext;
    return( hr );
  }
  *ppCtx = ( INSSUserAuthentication * )pContext;
  return( S_OK );
}

See Also

INSSUserAuthentication::GetAuthenticator


INSSAuthenticator::GetAuthenticatorClass

The INSSAuthenticator::GetAuthenticatorClass method is called to retrieve the class ID of the authenticator object.

Syntax

HRESULT GetAuthenticatorClass(
GUID *pCLSID
);

Parameters

[out] pCLSID

Specifies the class ID of the authenticator object.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CSampleAuthenticator::GetAuthenticatorClass( GUID *pCLSID )
{
  *pCLSID = CLSID_SampleAuthenticator;
  return( S_OK );
}

See Also

INSSAuthenticator::GetAuthenticationType


INSSAuthenticator::GetAuthenticationType

The INSSAuthenticator::GetAuthenticationType method is called to retrieve the type of authentication.

Syntax

HRESULT GetAuthenticationType(
LPBSTR bstrAuthenType
);

Parameters

[out] bstrAuthenType

Specifies the authentication type. Following is a list of authentication types currently supported by the server and player:

Type | Description
BASIC | HTTP-BASIC authentication
NTLM | NT LAN Manager authentication

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

The dwFlags parameter in INNSAuthenticator::Initialize must be NS_TEXT_WIRE_PROTOCOL when the authentication type is set to “BASIC”. The dwFlags parameter can not be NS_TEXT_WIRE_PROPTOCOL if the authentication type is “NTLM”,

Use the Automation allocation function SysAllocString to allocate memory for the string.

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CSampleAuthenticator::GetAuthenticationType(
                 BSTR * pbstrAuthenType )
{
  *pbstrAuthenType = SysAllocString( A2W ( "Basic" ) );
  if( NULL == *pbstrAuthenType )
  {
    return( E_OUTOFMEMORY );
  }
  return( S_OK );
}

See Also

INSSAuthenticator::GetAuthenticatorClass


INSSAuthenticator::Initialize

The INSSAuthenticator::Initialize method is called by the NetShow server at startup.

Syntax

HRESULT Initialize (
INSSServerContext *SvrCtx,
DWORD *dwFlags,
LPBSTR pbstrDefaultRealm
);

Parameters

[in] SvrCtx

Specifies a pointer to the server context. The server context contains name/value pairs of information (properties) about the server. These properties can be retrieved by using the IPropertyMap interface. Properties supported for the server context include the following;

Property Name | Description
NSS_SERVER_NAME | A string value containing the server’s name.
NSS_VIRTUAL_SERVER_NAME | A string value containing the server’s alias.
NSS_SERVER_VERSION_HI | The high-order 32 bits of a 64-bit integer specifying the version of NetShow Server. The most significant 16 bits of this property indicate the version. The least significant 16 bits of this property indicate the minor version.
NSS_SERVER_VERSION_LO | The low-order 32 bits of a 64-bit integer specifying the version of th NetShow Server. The most significant 16 bits of this property indicate the minor version. The least significant 16 bits of this property indicate the build number.

[out] dwFlags

Specifies a pointer to a flag indicating the format of data passed between the client, the server, and the authenticator. The value NS_TEXT_WIRE_PROTOCOL indicates that the data will be sent as a uuencoded ASCII string. Otherwise, the data is passed in binary form.

[Out] pbstrDefaultRealm

Specifies a pointer to the default realm. This realm string will be passed to the user as part of every challenge. If an authenticator always uses the same realm for user names, it should make domain\ computer-name as the default realm. Using a default realm helps to boost the performance of the server. If, on the other hand, an authenticator adopts a multi-step challenge/response scheme, this parameter should return a NULL pointer. In this case, the GetChallenge method should be used to obtain the realm each time the server challenges the client.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

The default realm may be overridden through the appropriate registry key.

Additional properties can be added to the server context. The properties contained in the server context are available from the time the server starts up until it shuts down.

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CSampleAuthenticator::Initialize(
    INSSServerContext *SvrCtx,
    DWORD *dwFlags )
{
  //
  // Do authenticator initialization here.
  //
  *dwFlags = NS_TEXT_WIRE_PROTOCOL; // set for uuencoded data
  return( S_OK );
}


INSSUserAuthentication

The INSSUserAuthentication interface exposes the following methods;

Method | Description
Authenticate | This method is called by the server to pass authentication data from the client to the authentication context.
GetAuthenticationResult | Retrieves the last results of the authentication.
GetAuthenticator | Retrieves a pointer to the authenticator object.
GetChallenge | This method is called by the server to get data the server will pass from the user authentication object to the client.
GetUserId | Retrieves a string containing the user ID after authentication is successfully completed.
Impersonate | Allows a server thread to impersonate the client.
Revert | Terminates impersonation.

Remarks

This interface is implemented by the developer.

See Also

INSSAuthenticationCallback, INSSAuthenticator


INSSUserAuthentication::Authenticate

The INSSUserAuthentication::Authenticate method is called when the client has authentication data to pass to the user authentication object.

Syntax

HRESULT Authenticate (
DWORD cbBlob,
BYTE *pBlob,
INSSAuthenticationCallback *pCallback,
DWORD dwRequestId
);

Parameters

[in] cbBlob

Specifies the size in bytes of the authentication data from the client.

[in] pBlob

Specifies a pointer to the authentication data from the client.

[in] Callback

Specifies a pointer to the callback method to call with the results

[in] dwRequestId

Specifies a DWORD specifying the request ID. The request ID is passed to the callback to uniquely identify this request.

Return Values

This method should always return S_Ok upon successful completion.

Remarks

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CUserAuthentication::Authenticate(
      DWORD cbBlob,
      BYTE *pBlob,
      INSSAuthenticationCallback *pCallback,
      DWORD dwRequestId )
{
  NS_AUTH_RESULT Result;
  //
  // Do the user authentication here.
  //
  //
  // Callback with the results.
  //
  pCallback->OnAuthenticateComplete(
          Result,
          ( INSSUserAuthentication * )this,
          dwRequestId );
  return( hr );
}

See Also

INSSUserAuthentication::GetChallenge, INSSAuthenticationCallback::OnAuthenticateComplete


INSSUserAuthentication::GetAuthenticationResult

The INSSAuthenticationContext::GetAuthenticationResult method is called to retrieve the results of the authentication.

Syntax

HRESULT GetAuthenticationResult (
NS_AUTH_RESULT *pResult
);

Parameters

[out] pResult

Specifies a pointer to the results of the authentication. Valid results include:

Results | Description
NS_AUTH_SUCCESS | Authentication is complete and the client was authenticated.
NS_AUTH_DENIED | Authentication is complete and the client could not be authenticated.
NS_AUTH_CONTINUE | More data is needed to complete authentication.
NS_AUTH_ERROR | An error occurred during authentication.
NS_AUTH_PENDING | Authentication is in progress.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CUserAuthentication::GetAuthenticationResult(
            NS_AUTH_RESULT *pResult )
{
  //
  // Set the results of the authentication.
  //
  return( S_OK );
}

See Also

INSSUserAuthentication::GetUserId


INSSUserAuthentication::GetAuthenticator

The INSSAuthenticationContext::GetAuthenticator method is called to retrieve a pointer to the authenticator that created the user-authentication object.

Syntax

HRESULT GetAuthenticator (
INSSAuthenticator **pAuth
);

Parameters

[out] pAuth

Specifies a pointer to the authenticator object.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CUserAuthentication::GetAuthenticator(
          INSSAuthenticator **pAuth )
{
  if( NULL == m_pAuthenticator )
  {
    return( E_NOINTERFACE );
  }

  *pAuth = m_pAuthenticator;
  //
  // Addref for the authenticator interface we are about to hand out.
  //
  m_pAuthenticator->AddRef();
  return( S_OK );
}

See Also

INSSAuthenticator::CreateUserAuthentication


INSSUserAuthentication::GetChallenge

The INSSUserAuthentication::GetChallenge method is called by the server to get data from the authenticator to be sent back to the client.

Syntax

HRESULT GetChallenge (
DWORD *pcbBlob,
BYTE **pBlob,
LPBSTR pbstrRealm
);

Parameters

[out] pcbBlob

Specifies the size in bytes of the data being sent to the client.

[out] pBlob

Specifies a pointer to the data being sent to the client.

[out] pbstrRealm

Specifies a pointer to the realm for the challenge.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

The authenticator determines the format of the returned challenge. In order to work properly with the server, the authenticator should observe the following guideline: If it is not obvious how the server will interpret the format, the authenticator should use the format appropriate for the text-based HTTP-Basic protocol.

If the INSSAuthenticator::Initialize method defines a NULL default realm, the GetChallenge method must return a non-NULL realm string. If the authenticator’s Initialize method specifies a non-NULL default realm, the pbstrRealm must be a NULL pointer. That is, the GetChallenge method should return any realm.

It is possible that the server may issue the GetChallenge method to get a realm and an initial challenge before the authenticator knows anything about the user. In this case, either the realm or the challenge, or both, may be NULL. Authenticators should be prepared to handle such cases so as to avoid unintended interruptions.

This method is called by the server when the result parameter passed to the callback has an NS_AUTH_CONTINUE value.

This method may also be called with an initial challenge to the client is made before the Authenticate method is called. This data may be ignored by the authenticator; however, a valid value should be returned to the server when the initial challenge is issued.

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CUserAuthentication::GetChallenge(
      DWORD *pcbBlob,
      BYTE **pBlob )
{
  //
  // Set the blob with the reply data here.
  //
  return( S_OK );
}

See Also

INSSUserAuthentication::Authenticate, INSSAuthenticationCallback::OnAuthenticateComplete


INSSUserAuthentication::GetUserId

The INSSUserAuthentication::GetUserId method is called after authentication to retrieve the user ID.

Syntax

HRESULT GetUserId (
BSTR **pbstrUserId
);

Parameters

[out] pbstrUserId

Specifies the address of a pointer to the authenticated user ID.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

This method should only be called after authentication is complete, and only if the result is NS_AUTH_SUCCESS. The results of authentication can be determined by calling the INSSUserAuthentication::GetAuthenticationResult method.

Use the automation allocation function SysAllocString to allocate the user ID string.

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CUserAuthentication::GetUserId( BSTR *pbstrUserId )
{
  //
  // Get the user id.
  //
  *pbstrUserId = SysAllocString (A2W (“User Name”) );
  if ( NULL == ( *pbstrUserId ) )
  {
    return ( E_OUTOFMEMORY );
  }
  return( S_OK );
}

See Also

INSSUserAuthentication::GetAuthenticationResult


INSSUserAuthentication::Impersonate

The INSSUserAuthentication::Impersonate method is used to allow the server to impersonate the authentication context of the client.

Syntax

HRESULT Impersonate ( );

Parameters

This method has no parameters

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

This method should only be called after authentication is complete, and only if the result is NS_AUTH_SUCCESS. The results of authentication can be determined by calling the INSSUserAuthentication::GetAuthenticationResult method.

While the server thread is impersonating the client, it is subject to the same access controls as the client.

Authenticators typically implement this method by calling the following functions:

  • For HTTP-BASIC authentication, call the Microsoft® Win32® function ImpersonateLoggedOnUser.
  • For NTLM authentication, call the SSPI function ImpersonateSecurityContext.

See Also

INSSUserAuthentication::Revert, INSSUserAuthentication::GetAuthenticationResult


INSSUserAuthentication::Revert

The INSSUserAuthentication::Revert method is used to terminate impersonation.

Syntax

HRESULT Revert ( );

Parameters

This method has no parameters

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

This method should only be called after authentication is complete, and only if the result is NS_AUTH_SUCCESS. The results of authentication can be determined by calling the INSSAuthenticationContext::GetAuthenticationResult method.

Authenticators typically implement this method by calling the following functions:

  • For HTTP-BASIC authentication, call the Win32 function RevertToSelf.
  • For NTLM authentication, call the SSPI function RevertSecurityContext.

See Also

INSSUserAuthentication::Impersonate, INSSUserAuthentication::GetAuthenticationResult


NetShow Authentication API Sample

The DBAuthen application is a sample using the NetShow Authentication API to develop authentication plug-in component.

Sample | Purpose and description
DBAuthenticator | Authentication component that checks client credentials against a database.

To test the SDK sample, you should have the appropriate ActiveX controls installed in your system. It is recommended that you run these samples on a machine that has NetShow installed. To download the complete suite of NetShow products visit the NetShow web site http://www.microsoft.com/NetShow


NetShow Event Notification and Authorization API

[This is preliminary documentation and subject to change.]

The Microsoft® NetShow™ Unicast Server provides an API for developing event notification and authorization plug-in components. These components extend the NetShow server providing tools to authorize content playing, server state monitoring, and transaction auditing.

In this portion of the SDK, we present a brief overview of authorization and the general foundation of the NetShow Event Notification and Authorization components. We then describe how to use the Event Notification and Authorization API to create these components.

The discussion is divided into the following topics.

Subject | Description
About the Event Notification and Authorization API | This section introduces the general concept of authorization, and discusses the architecture of an event notification and authorization component.
Using the Event Notification and Authorization API | This section describes how the NetShow server interacts with the event handling and authorization component, and how you register the componnet in the system registry.
Event Notification and Authorization Reference | This section describes the specifications for implementing the COM interfaces of the notification and authorization component.
Event Notification and Authorization API Samples | This section discusses three sample applications that illustrate how to develop NetShow authentication event notification and authorization plug-in components to implement pay per view and pay per minute business plans, and perform membership validation.


About the Event Notification and Authorization API

Authorization refers to a security feature for granting or denying access to protected resources. For NetShow, the protected resources include Pay-Per-View (PPV) or Pay-Per-Minute (PPM) titles, or free but otherwise sensitive content. Authorization works hand-in-hand with authentication that serves to confirm the user identity. In general, a user who has failed authentication will not have permission to access the requested resource. A NetShow content provider may choose to grant an authenticated user limited or unlimited accesses to the requested title only after the user has accepted posted terms of agreement or has submitted a valid credit card number.

A server can be configured to implement authorization as a service or via plug-in components. Delegating such tasks to dedicated plug-in components gives service providers the flexibility to implement different authorization schemes to meet different business needs. A plug-in component is responsible for not only carrying out the business policy, but also responding to event notificatioins. The NetShow server supports any number of plug-in components running simultaneously. Each component can specify a unique set of events for notification and authorization.

The NetShow Event Notification and Authorization API helps you to focus on the business logic by providing a common protocol for developing COM-compliant plug-in components that perform authorization on behalf of the NetShow server when specified events occur. The API lets you leverage the established application infrastructure.

As COM objects, these plug-in components must be properly registered before they can be instantiated and initialized. At startup, the server queries the components to determine the type of events that require authorization and notification. When a client makes a request, the server attempts to trigger one of the specified events and solicits the associated component for approval. After granting or denying the access, the server notifies the component of the outcome of the event. For example, the component could specify that the Play event requires authorization and notification. When a client asks the server to play a title, the server first seeks permission from the component, which in turns tries to secure an appropriate payment plan before granting permission to stream the title. When the authorization is successful, the server starts playing the title and notifies the component that the Play event is underway. The component can then proceed to audit the playing time for billing.


Applications of Event Notification and Authorization Components

Using the NetShow Event Notification and Authorization API, you can develop plug-in components to perform a wide-range of authorization related tasks, including:

  • Restricting access to protected material.
  • Billing customers for viewing NetShow content.
  • Performing usage analysis of NetShow presentations.
  • Tracking client preferences for selectively targeted advertising.

The plug-in components can work either inside corporate firewalls or across the Internet. The following diagram illustrates the integration of the NetShow Authorization security package and a Web site manager:


Event Notification and Authorization Interfaces

The NetShow Event Notification and Authorization API is comprised of two custom COM-compliant interfaces and one server callback interface. As a developer, you are responsible for implementing the two component-side interfaces, namely INSSEventHandler, and INSSEventAuthorization. These two interfaces are invoked by the NetShow server. The third one is the INSSEventAuthorizationCallback interface, which is implemented by the server and invoked by the component. The NetShow server also employs several context objects that implement IPropertyMap, a generic and prepackaged interface for manipulating named parameters. Following is a brief description of these interfaces.

Interface | Description
INSSEventHandler | The methods of this interface are called by the server when specified events occur. It is also used to select which events will trigger a call to the interface and to perform initialization and shutdown tasks. This interface is implemented by the developer.
INSSEventAuthorization | The methods of this interface are called by the server when a request has been made to perform a specified task. The server does not grant the request until it receives permission from the authorization routine. This interface is also used to specify which requests will trigger a call to this interface. This interface is implemented by the developer.
INSSEventAuthorizationCallback | The callback method of this interface is used to notify the server when the requested event has been authorized or denied. This interface is implemented by the server.

A component must be able to handle events even if it is not required to perform authorization. Thus, each component must implment the INNSEventHandler event notification interface. Every component can selectively respond to event notifications issued from the server. You implement the INNSEventHandler::GetHandleEvents method to specify the types of events to be notified. In addition to handling events, the event notification interface serves to initialize the component when the server starts, to monitor the operational state of the server, and to terminate itself when the server is down.

The INSSEventAuthorization interface deals with event authorization only. A component implements this interface only when it is interested in authorization. There are only two methods in this interface: GetAuthorizedEvents, which specifies the type of events requiring authorization, and AuthorizeEvent, which performs the actual process of authorization. An event may require authorization, but not notification.

Any number of different components may be registered for event authorization. For example, one component authorizes the Play event based on the pay-per-view plan, and another on the pay-per-minute plan. When more than one component is registered, the server calls the methods of the authorization interface of each component in turn. The server will not grant the request until it receives permission from all the registered components. If any component denies the request, the server will not grant permission and will notify all the components of the denial. Thus, a component should grant permission to any request of the event authorization that is outside of the scope of its prescribed responsibility. For example, a pay-per-view authorization component should not deny requests for pay-per-minute title.

For performance reasons, a single component capable of handling different authorization schemes is prefered to multiple components handling a single authorization scheme. A single component implementation helps to reduce the number of client/server interactions.


Using the Event Notification and Authorization API

This section discusses the guidelines for developing and exporting the interfaces necessary for event notification and authorization. The Reference section provides a detailed discussion of the implementation of the interfaces and the data structures they use.


NetShow Event Notification and Authorization Scheme

The following diagram outlines the interaction between the NetShow server, an event notification and authorization plug-in component, and a client:


Calls to the Event Notification and Authorization API

The NetShow Event Notification and Authorization components use contexts to hold and pass around information about the server, user, or content. A context is an object wrapper of a data set and implements certain interface for manipulating the encapsulated data. For example, a server context encapsulates server information and exposes methods to access or to manipulate the server without having to know its underlying data structures. To have a plug-in component work with the server, user, or content amounts to specifying the appropriate server, user, or presentation context in the component and calling the methods of the interface. The context interfaces in NetShow inherit from the IPropertyMap interface. For more information about contexts supported by NetShow, see the discussion of “Event Notification Authorizatioin Contexts” in this document.

When the NetShow server is started, it retrieves from the system registry the class identifier (CLSID), and creates instances of all the notification and authorization plug-in components. Then the server and the components proceed to interact with each other in the following order.

Initialization

The NetShow server calls the INSSEventHandler::Initialize method on each component to initialize the instantiated objects. The server passes in a pointer to the server context so that a component can use it to retrieve information about the server. The retrievable information includes:

  • The name of the server.
  • The server’s virtual name.
  • The version and build numbers of the server.

The server context is available as long as the server is running. Later, the server can pass additional contexts into a component, such as a user context or a presentation context.

Setting a Heartbeat

NetShow defines a heartbeat as a server timer event. A heartbeat can be used for timing other events and for monitoring the operational state of the server. You can have the server enable the heartbeat by specifying a positive value for the dwMsHeartbeatPeriod parameter in the Initialize method of the INNSSEventHandler interface. If a heartbeat is enabled, the server calls the INSSEventHandler::OnHeartbeat method at the regular intervals of the specified heartbeat period. Setting the dwMsHeartbeatPeriod parameter to zero disables the heartbeat.

For billing purposes, notification and authorization components can start their own timer events. For example, a component that authorizes the pay-per-minute Play event can start a timer once the user begins playing a title and can stop the timer when the user finishes viewing the title. The period of time from the start of play to the finish may be billable to the client if the server is up and running for the entire period. If, on the other hand, the server is down for sometime, the time interval clocked with the component’s timer may not be appropriate for the billing purpose. In this case, heartbeat is a preferred measure of time, because the OnHeartbeat method is only called while the server is up and running.

Specifying Notification Events

After initialization the server calls the INSSEventHandler::GetHandledEvents method of each component. This method is used to select events that will trigger a call to the event handler by the server. The following types of events are supported for notification.

  • Clients connecting and disconnecting to and from the server.
  • Opening and closing titles.
  • Starting and stopping titles.
  • Skiping or enabling client authentication.

Test for Authorization Support

After notification events are set, the server calls the QueryInterface method of the INSSEventAuthorization interface to determine whether or not the authorization interface is supported. All components must implement the INSSEventHandler interface. However, the INSSEventAuthorization interface is optional. When authorization is supported, the server invokes the INSSEventAuthorization::GetAuthorizedEvents method to retrieve the array of authorized events and thus determines which events will require authorization.

Specifying Authorization Events

A component specifies which event must undergo the authorization process. You implement the scheme with the INSSEventAuthorization::GetAuthorizedEvents method. This method is similar to that specifying the events for notification. However, fewer events are supported for authorization. For instance, requiring authorization from the server before the client disconnects is not useful because the server cannot prevent a client from disconnecting.

You can specify the following events for authorization:

  • Clients connecting to the server.
  • Opening a title.
  • Playing a title.
  • Skipping client authentication.

Authorization

The NetShow server calls the INSSEventAuthorization::AuthorizeEvent method to determine whether it will perform the task assoicated with an event that requires authorization. When calling the method, the server supplies the component with information about the event, client, and content to be authorized.

If the authorization is a complicated and lengthy process, you should implement the AuthorizeEvent method in an asynchronous fashion, spawning another thread to determine if the request should be granted. Asynchronous implementation results in an immediate return of calls to the method and frees the server to proceed with other tasks while the authorization is in process. However, if the authorization is simple, as is in most cases, the method should return synchronously; that is, return a call after the authorization is done.

At the end of the authorization process, whether the request is granted or denied, the authorization component makes a call to the server to invoke the INSSEventAuthorizationCallback::OnEventAuthorizedmethod. A pointer to the callback interface is passed in by the server when it invokes the AuthorizeEvent method. The authorization component must call this method, whether the AuthorizeEvent method returns synchronously or asynchronously.

To uniquely identify the event requested for authorization, both the server and the authorization component pass the dwRequestId parameter to each other. The server passes the parameter into the component through the call to the INSSEventAuthorization::AuthorizeEvent method. The authorization component must pass the same request identifier back to the server through the call to the INSSEventAuthorizationCallback::OnEventAuthorized method.

Event Notification

Suppose that a user choses to play a title. If authorization is required to play the title, the server asks the event notification and authorization component to check on the user. When the user is authorized to play the title, the server then opens the title for user to play. If the authorization fails, the server will not open the requested title. In either case, the server calls the INSSEventHandler::HandleEvent method to notify the component whether or not the event occurs (in this case, whether the title is being played or not). If authorization is not required, the server will open the title for the user and then notify the component that the title is being played.

The server also notifies the component of any other events that are registered for notification and/or authorization by using the INSSEventHandler::GetHandleEvents method. The notification specifies the type of event requested and the results of the authorization, when applicable. You can choose to implement different responses to the notification in the INSSEventHandler::HandleEvents method. For example, you can present the viewing statistics of the client when the user connects to the server. Or you can announce the charge inccurred by the viewer when the title is stopped.

Event Notification and Authorization Framework

The following diagram illustrates a simple model of the sequence of calls between the NetShow server and the event notification and authorization interfaces. This chart assumes that there is only one authorization interface, and does not address client authentication.


Event Notification Authorization Contexts

A context is an object that inherits and implements the IPropertyMap interface that manipulates the encapsulated member data. When the encapsulated data define a server, a user, or some content, the object is known as a server context, a user context, or a presentation context, respectively. The NetShow server uses contexts to pass client, server, and presentation data to the notification and authorization components. The IPropertyMap interface supports methods for adding, removing, evaluating, and modifying the properties of name/value pairs of data. The NetShow server maintains several different contexts to describe different aspects of each server task. Contexts supported by the server include the following:

Context | Description
Server | Contains information about the Netshow server.
User | Contains information about the client.
Presentation | Contains information about the media stream.
Command | Reserved for future implementation.

Server Context Properties

Following is a list of predefined server context properties that are maintained by the server:

Property Name | Description
NSS_SERVER_NAME | A string value containing the server’s name.
NSS_VIRTUAL_SERVER_NAME | A string value containing the server’s alias.
NSS_SERVER_VERSION_HI | The high-order 32 bits of a 64-bit integer specifying the version of the NetShow server. The most significant 16 bits of this property indicate the version. The least significant 16 bits of this property indicate the minor version.
NSS_SERVER_VERSION_LO | The low-order 32 bits of a 64-bit integer specifying the version of the NetShow server. The most significant 16 bits of this property indicate the minor minor version. The least significant 16 bits of this property indicate the build number.

User Context Properties

Following is a list of predefined user context properties that are maintained by the server:

Property Name | Description
NSS_USER_AGENT | A String value containing the information about the user connecting to the server. It can be used to differentiate whether the connected user is a player or another server. This property may not contain valid information if it is stripped by a proxy.
NSS_USER_IP_ADDRESS | A String value containing the user’s IP address. The IP address may not be meaningful if it is masked by a firewall. The value of this property may change for different connections of the same client.
NSS_USER_CONTROL_PROTOCOL | A String value containing the protocol type. Valid types include; MMS, RTSP, HTTP, and UNKNOWN.
NSS_USER_ID | A String value containing the client ID. This ID corresponds with the ClientId property of the NetShow Unicast Manager Admin control, and it can be used to disconnect the client.
NSS_USER_NAME | A String value containing the user name. This property is only valid after the user has been successfully authenticated.
NSS_USER_AUTHENTICATOR | A pointer to the IUnknown interface of the authenticator object used to authenticate the user.
NSS_USER_GUID | A String value containing the client GUID. This GUID is generated when the player is installed on the client computer.

Presentation Context Properties

Following is a list of predefined presentation context properties that are maintained by the server:

Property Name | Description
NSS_PRESENT_LIVE | A Boolean value specifying whether or not the presentation is live.
NSS_PRESENT_BROADCAST | A Boolean value specifying whether or not the presentation is being broadcast.
NSS_PRESENT_SEEKABLE | A Boolean value specifying whether or not the file supports seeking to a specific time or marker.
NSS_PRESENT_STRIDABLE | A Boolean value specifying whether or not the file supports fast forward and rewind.
NSS_PRESENT_RELIABLE | A Boolean value specifying whether or not the presentation is reliable.
NSS_PRESENT_PHYSICAL_NAME | A String value containing the name of the file being streamed.
NSS_PRESENT_REQUEST_NAME | A String value containing the name the client used to request the presentation.
NSS_PRESENT_BITRATE | A floating-point value indicating the bit-rate of the stream.
NSS_PRESENT_DURATION_HI | The high-order 32 bits of a 64-bit integer indicating the duration of the movie in miliseconds.
NSS_PRESENT_DURATION_LO | The low-order 32 bits of a 64-bit integer indicating the duration of the movie in miliseconds.
NSS_PRESENT_FRAMES_PER_SEC | An integer indicating the number of frames per second.
NSS_PRESENT_PLAY_RATE | A floating-point value indicating the play rate of the presentation. A value of 1 indicates normal speed. Values greater than 1 indicate that the presentation is being fast-forwarded, and negative values indicate rewind.
NSS_PRESENT_START_POS_HI | The high-order 32 bits of a 64-bit integer indicating the starting position of the movie.
NSS_PRESENT_START_POS_LO | The low-order 32 bits of a 64-bit integer indicating the starting position of the movie.
NSS_PRESENT_TOTAL_BYTES_SENT_HI | The high-order 32 bits of a 64-bit integer indicating the total number of bytes of the presentation that were sent to the client.
NSS_PRESENT_TOTAL_BYTES_SENT_LO | The low-order 32 bits of a 64-bit integer indicating the total number of bytes of the presentation that were sent to the client.
NSS_PRESENT_TOTAL_PLAY_TIME_HI | The high-order 32 bits of a 64-bit integer indicating the total time the presentation was streamed to the client in milliseconds.
NSS_PRESENT_TOTAL_PLAY_TIME_LO | The low-order 32 bits of a 64-bit integer indicating the total time the presentation was streamed to the client in milliseconds.

Context Properties Set by the Server

The server sets different context properties for different types of events. The following table lists the property values that are set by the server for initialization or when authorization or notification of an event occurs:

Events Properties Set By Server
When initialization occurs Server Context:
NSS_SERVER_NAME
NSS_VIRTUAL_SERVER_NAME
NSS_SERVER_VERSION_HI
NSS_SERVER_VERSION_LO
NSSE_CONNECT and

NSSE_DISCONNECT

 Server Context:
NSS_SERVER_NAME
NSS_VIRTUAL_SERVER_NAME
NSS_SERVER_VERSION_HI
NSS_SERVER_VERSION_LO

User Context:
NSS_USER_AGENT
NSS_USER_IP_ADDRESS
NSS_USER_CONTROL_PROTOCOL
NSS_USER_ID
NSSE_SKIP_AUTHENTICATION Server Context:
NSS_SERVER_NAME
NSS_VIRTUAL_SERVER_NAME
NSS_SERVER_VERSION_HI
NSS_SERVER_VERSION_LO

User Context:
NSS_USER_AGENT
NSS_USER_IP_ADDRESS
NSS_USER_CONTROL_PROTOCOL
NSS_USER_ID

Presentation Context:
NSS_PRESENT_PHYSICAL_NAME
NSS_PRESENT_REQUEST_NAME
NSSE_OPEN and

NSSE_CLOSE

 Server Context:
NSS_SERVER_NAME
NSS_VIRTUAL_SERVER_NAME
NSS_SERVER_VERSION_HI
NSS_SERVER_VERSION_LO

User Context:
NSS_USER_AGENT
NSS_USER_IP_ADDRESS
NSS_USER_CONTROL_PROTOCOL
NSS_USER_ID
NSS_USER_AUTHENTICATOR
NSS_USER_NAME

Presentation Context:
NSS_PRESENT_PHYSICAL_NAME
NSS_PRESENT_REQUEST_NAME
NSSE_PLAY and

NSSE_STOP

* items are only set for the NSSE_STOP event.

 Server Context:
NSS_SERVER_NAME
NSS_VIRTUAL_SERVER_NAME
NSS_SERVER_VERSION_HI
NSS_SERVER_VERSION_LO

User Context:
NSS_USER_AGENT
NSS_USER_IP_ADDRESS
NSS_USER_CONTROL_PROTOCOL
NSS_USER_ID
NSS_USER_AUTHENTICATOR
NSS_USER_NAME

Presentation Context:
NSS_PRESENT_PHYSICAL_NAME
NSS_PRESENT_REQUEST_NAME
NSS_PRESENT_STREAMID
NSS_PRESENT_BITRATE
NSS_PRESENT_DURATION_HI
NSS_PRESENT_DURATION_LO
NSS_PRESENT_LIVE
NSS_PRESENT_BROADCAST
NSS_PRESENT_SEEKABLE
NSS_PRESENT_RELIABLE
NSS_PRESENT_RECORDABLE
NSS_PRESENT_PLAY_RATE
NSS_PRESENT_START_POS_HI
NSS_PRESENT_START_POS_LO

*NSS_PRESENT_TOTAL_BYTES_SENT_HI
*NSS_PRESENT_TOTAL_BYTES_SENT_LO
*NSS_PRESENT_TOTAL_PLAY_TIME_HI
*NSS_PRESENT_TOTAL_PLAY_TIME_LO

Note The NSS_USER_AUTHENTICATOR and NSS_USER_NAME properties are NOT set by the server unless authentication is enabled and the user has successfully been authenticated.

Context Properties set by a Component

The notification and authorization component can add new properties to the server, user, or presentation contexts, and set or retrieve the existing properties at any time during the life of the context. For example, the fee charged for viewing the title can be added to the presentation context when the title is opened. Then the billing cost can easily be retrieved from the context when the server sends notification that the title has been closed.

Context Lifetimes

Each context holds the value of its properties for a predetermined duration or lifetime. The values contained in the context can be set and retrieved until the end of that context’s lifetime. The following table details the lifespans of the contexts:

Context | Lifetime
Server | Always available.
User | Available from the time the client connects to the server up to the time the client disconnects.
Presentation | Available from the time the title is opened up to the time the title is closed. A new presentation context is created for each title that is opened by each client.

Note: The pointer to the context may be lost immediately after the method returns. To maintain access to the properties during asynchronous calls, call AddRef to increment the interface’s reference counter. Alternately, the data needed by the component could be stored in temporary variables. If AddRef is used, the component should call Release to free the pointer when the context is no longer needed.

Property Map Example

The following code demonstrates how you can retrieve the user name from the user context:

HRESULT hres;
VARIANT userName;
  hres = pUser->QueryInterface(IID_IPropertyMap,
           (void**) &pIUserPropMap);
  hres = pIUserPropMap->Read(_T("NSS_USER_NAME"),
              &userName);


Registering the Event Notification and Authorization Components

Registering Event Notification and Authorization Components

Add the following key to the registry for event notification and authorization components:

[HKEY_LOCAL_MACHINE\Software\Microsoft\NetShow\Servers\
\Default\Event Notification]

At startup, the server checks the registry and instantiates each of the components listed under this key.

Following is an example of the values that should be added to the Event Notification key;

[HKEY_LOCAL_MACHINE\Software\Microsoft\NetShow\Servers\
\Default\Event Notification\Sample Billing Module]
"CLSID"="{16DA4310-2955-11D1-9E98-006097D2D7CF}"
"Description"="Sample billing module"
"Author"="Developer Name"
"Copyright"="(c) Developer 1997"
"Enabled"=dword:00000001
"Index"=dword:00000000

{Description of these values goes here!}

Note: Every plug-in component supports notification, support for authorization is optional. The server calls the QueryInterface method to determine if the component supports authorization.

The NetShow server will load any registered components, including the disabled ones, and then invoke their Initialize method. The server will not stream any video unless all the registered components yield a successful return from the Initialize method. Thus, you you remove the whole registry entry of an unwanted component, instead of merely disabling it using the “Enabled” registry key.


Event Notification and Authorization Reference

This reference provides detailed descriptions of the interfaces implemented by and for the NetShow server, and the structures supported for their implementation.


NetShow Event Notification and Authorization Interfaces

The interface descriptions in the reference section of this SDK specify the requirements for COM-compliant interfaces that must be implemented by the developer, except for INSSEventAuthorizationCallback, which is implemented by the NetShow server. All methods are listed in Vtable order. The NetShow Event Notification and Authorization interfaces include the following;

  • INSSEventAuthorization
  • INSSEventHandler
  • INSSEventAuthorizationCallback


INSSEventAuthorization

In addition to the methods implemented by IUnknown, the following methods must be implemented for the INSSEventAuthorization interface;

Method | Description
GetAuthorizedEvents | Specifies the events that will trigger calls to the AuthorizeEvent method.
AuthorizeEvent | Sent when a specified event is requested.

See Also

INSSEventHandler, INSSEventAuthorizationCallback


INSSEventAuthorization::GetAuthorizedEvents

The INSSEventAuthorization::GetAuthorizedEvents method is used to specify which events must be authorized before they can be performed.

Syntax

HRESULT GetAuthorizedEvents (
DWORD cMaxAuthorizedEvents,
DWORD *pcAuthorizedEvents,
NSS_EVENT_TYPE *rgAuthorizedEvents
);

Parameters

[in] cMaxAuthorizedEvents

Indicates the maximum number of events that can be specified for authorization.

[out] pcAuthorizedEvents

Specifies the number of authorization events being set by the component.

[out] rgAuthorizedEvents

Specifies the list of events requiring authorization. Each event specified by this parameter triggers a call from the server to the component’s INSSEventAuthorization::AuthorizeEvent method. Values supported for this parameter include:

Event Type | Description
NSSE_CONNECT | Client requests a connection.
NSSE_OPEN | Request to open a title.
NSSE_PLAY | Request to start streaming title.
NSSE_SKIP_AUTHENTICATION | Require user authentication.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

Memory for the events specified by rgAuthorizedEvents is allocated and freed by the server.

The following code illustrates a skeleton implementation of the INSSEventAuthorization::GetAuthorizedEvents method.

HRESULT
CEventHandler::GetAuthorizedEvents(
    DWORD cMaxAuthorizedEvents,
    DWORD __RPC_FAR *pcAuthorizedEvents,
    NSS_EVENT_TYPE __RPC_FAR *rgAuthorizedEvents )
{
  if ( ( NULL == rgAuthorizedEvents )
    || ( NULL == pcAuthorizedEvents )
    || ( cMaxAuthorizedEvents < 3 ) )
  {
    return( E_INVALIDARG );
  }
  *pcAuthorizedEvents = 3;
  rgAuthorizedEvents[0] = NSSE_CONNECT;
  rgAuthorizedEvents[1] = NSSE_OPEN;
  rgAuthorizedEvents[2] = NSSE_PLAY;
  return(S_OK);
};

See Also

INSSEventAuthorizationCallback::OnEventAuthorized , NSS_EVENT_TYPE


INSSEventAuthorization::AuthorizeEvent

The INSSEventAuthorization::AuthorizeEvent method is called when a specified event is requested.

Syntax

HRESULT AuthorizeEvent (
NSS_EVENT *pEvents,
INSSUserContext *pUser,
INSSPresentationContext *pPresentation,
INSSEventAuthorizationCallback *pCallback,
DWORD dwRequestId
);

Parameters

[in] pEvents

Specifies the server event being authorized.

[in] pUser

Specifies a pointer to the user context. The user context is used to store information about the client. For more information about the user context and its properties, see Event Authorization and Notification Contexts in the guide.

[in] pPresentation

Specifies a pointer to the presentation context property map interface. The presentation context is used to store information about the presentation. For more information about the presentation context and its properties, see Event Authorization and Notification Contexts in the guide.

[in] pCallback

Specifies a pointer to the INSSEventAuthorizationCallback::OnEventAuthorized callback method authorizing the server to perform the requested event. The callback interface is implemented by the server.

[in] dwRequestId

Specifies the request ID. This parameter is passed back to the INSSEventAuthorizationCallback::OnEventAuthorized method to uniquely identify the event being requested.

Return Values

This method should return S_OK upon successful completion. Authorization errors should be passed to the callback interface.

Remarks

A request from a client to perform any of the events specified by the INSSEventAuthorization::GetAuthorizedEvents method triggers a call to this method.

If the authorization process is expected to be lengthy, the call into this method can use another thread to check authorization and return immediately so the server won’t be tied up.

The following code illustrates a skeleton implementation of the INSSEventAuthorization::AuthorizeEvent method;

HRESULT
CEventHandler::AuthorizeEvent(
      NSS_EVENT __RPC_FAR *pEvent,
      INSSUserContext __RPC_FAR *pUser,
      INSSPresentationContext __RPC_FAR *pPresentation,
      INSSCommandContext __RPC_FAR *pCommand,
      INSSEventAuthorizationCallback __RPC_FAR *pCallback,
      DWORD dwRequestId )
{
  HRESULT hr;

  if ( ( NULL == pEvent )
    || ( NULL == pCallback ) )
  {
    return( E_INVALIDARG );
  }
//
// The authorization routine goes here. The results of the authorization
// is sent to the call back in the hr parameter
//
  pCallback->OnEventAuthorized( hr, dwRequestId );
  return( S_OK );
};

See Also

INSSEventAuthorization::GetAuthorizedEvents; INSSEventAuthorizationCallback::OnEventAuthorized


INSSEventAuthorizationCallback

In addition to the methods implemented by IUnknown, the INSSEventAuthorizationCallback interface exposes the following method:

Method | Description
OnEventAuthorized | Reports results of the authorization to the server.

Remarks

This interface is implemented by the server to handle authorization of events triggered by calls to the INSSEventAuthorization::AuthorizeEvent method.

See Also

INSSEventAuthorization::AuthorizeEvent


INSSEventAuthorizationCallback::OnEventAuthorized

The INSSEventAuthorizationCallback::OnEventAuthorized method is used to inform the server of the results of the authorization.

Syntax

HRESULT OnEventAuthorized (
HRESULT hr,
DWORD dwRequestId
);

Parameters

[in] hr

Specifies the results of the authorization. If this parameter is set to S_OK, the server will perform the task.

[in] dwRequestId

Specifies the request ID. This parameter is passed from the server to the authorization interface through the INSSEventAuthorization::AuthorizeEventmethod.

Return Values

This method should return S_OK upon successful completion.

See Also

INSSEventAuthorization::AuthorizeEvent


INSSEventHandler

In addition to the methods implemented by IUnknown, the following methods must be implemented for the INSSEventHandler interface;

Method | Description
Initialize | Called when the NetShow server starts.
GetHandledEvents | Specifies the events that will trigger calls to the HandleEvent method for this component.
Shutdown | Called when the NetShow server is stopped.
OnHeartbeat | Called by the server at each heartbeat period.
HandleEvent | Called when a specified event occurs.

Remarks

This interface is implemented by the developer.

See Also

INSSEventAuthorization


INSSEventHandler::Initialize

The INSSEventHandler::Initialize method is called when the NetShow server starts up.

Syntax

HRESULT Initialize (
INSSServerContext *pServer,
DWORD *pdwMsHeartbeatPeriod
);

Parameters

[in] pServer

Specifies a pointer to the server context. The server context is used to store information about the NetShow server. For more about information about the server context and its properties, see Event Authorization and Notification Contexts in the guide.

[out] pdwMsHeartbeatPeriod

Specifies the heartbeat period measured in milliseconds. The server sends an NSSE_HEARTBEAT event on the interval specified by this parameter.

A value of zero specifies no heartbeat events will be sent.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

Every authorization and event notification component must support the INSSEventHandler interface and the Initialize method. This method is used to initialize the entire component and not just the event handler interface.

The following code illustrates a skeleton implementation of the INSSEventHandler::Initialize method.

HRESULT
CEventHandler::Initialize(
      INSSServerContext __RPC_FAR *pServer,
      DWORD __RPC_FAR *pdwHeartbeatPeriod )
{
  *pdwHeartbeatPeriod = 0; // No heartbeat events are required.
  return( S_OK );
}

See Also

INSSEventHandler::Shutdown, INSSEventHandler::OnHeartbeat


INSSEventHandler::GetHandledEvents

The INSSEventHandler::GetHandledEvents method is used to specify which events will trigger a call from the NetShow server.

Syntax

HRESULT GetHandledEvents (
DWORD cMaxHandledEvents,
DWORD *pcHandledEvents,
NSS_EVENT_TYPE *rgHandledEvents
);

Parameters

[in] cMaxHandledEvents

Specifies the maximum number of different handled events.

[out] pcHandledEvent

Specifies the number of events in the rgHandledEvent parameter.

[out] rgHandledEvent

Specifies the list of events that will trigger a call from the server to the INSSEventHandler::HandleEvent method. Supported values for this parameter are:

Event Type | Description
NSSE_CONNECT | Client connected
NSSE_DISCONNECT | Client disconnected
NSSE_OPEN | Title opened
NSSE_CLOSE | Title closed
NSSE_PLAY | Title started streaming
NSSE_STOP | Title stopped streaming

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

Memory for the events specified by the rgAuthorizedEvents is allocated and freed by the server.

The following code illustrates a skeleton implementation of the INSSEventHandler::GetHandledEvents method:

HRESULT
CEventHandler::GetHandledEvents(
        DWORD cMaxHandledEvents,
        DWORD __RPC_FAR *pcHandledEvents,
        NSS_EVENT_TYPE __RPC_FAR *rgHandledEvents )
{
  if ( ( NULL == pcHandledEvents )
    || ( NULL == pcHandledEvents )
    || ( cMaxHandledEvents < 9 ) ) {
    return( E_INVALIDARG );
  }
  *pcHandledEvents = 6;
  rgHandledEvents[0] = NSSE_CONNECT;
  rgHandledEvents[1] = NSSE_DISCONNECT;
  rgHandledEvents[2] = NSSE_OPEN;
  rgHandledEvents[3] = NSSE_CLOSE;
  rgHandledEvents[4] = NSSE_PLAY;
  rgHandledEvents[5] = NSSE_STOP;
  return( S_OK );
}

See Also

INSSEventHandler::HandleEvent


INSSEventHandler::Shutdown

The INSSEventHandler::Shutdown method is called when the NetShow server is shutdown.

Syntax

HRESULT Shutdown ( );

Parameters

None

Return Values

This method should return S_OK after successfully freeing all system resources allocated by the component.

Remarks

The following code illustrates a skeleton implementation of the INSSEventHandler::Shutdown method:

HRESULT
CEventHandler::Shutdown()
{
  return( S_OK );
}

See Also

INSSEventHandler::Initialize


INSSEventHandler::OnHeartbeat

The INSSEventHandler::OnHeartbeat method is called by the server at each heartbeat period.

Syntax

HRESULT OnHeartbeat ( );

Parameters

None

Return Values

This method should return S_OK.

Remarks

The following code illustrates a skeleton implementation of the INSSEventHandler::OnHeartbeat method:

HRESULT
CEventHandler::OnHeartbeat()
{
  // Increment counter for each client.
  return( S_OK );
}

See Also

INSSEventHandler::Initialize


INSSEventHandler::HandleEvent

The INSSEventHandler::HandleEvent method is called when specified events are sent from the NetShow server.

Syntax

HRESULT GetHandledEvents (
NSS_EVENT *pEvent,
INSSUserContext *pUser,
INSSPresentationContext *pPresentation,
INSSCommandContext *pCommand
);

Parameters

[in] pEvent

Specifies a pointer to the event and the results of authorization.

[in] pUser

Specifies a pointer to the user context property map interface. The user context is used to store information about the client. For more information about the user context and its properties, see Event Authorization and Notification Contexts in the guide.

[in] pPresentation

Specifies a pointer to the presentation context property map interface. The presentation context is used to store information about the presentation. For more information about the presentation context and its properties, see Event Authorization and Notification Contexts in the guide.

[in] pCommand

Specifies the command context.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

The following code illustrates a skeleton implementation of the INSSEventHandler::HandleEvent method:

HRESULT
CEventHandler::HandleEvent(
        NSS_EVENT __RPC_FAR *pEvent,
        INSSUserContext __RPC_FAR *pUser,
        INSSPresentationContext __RPC_FAR *pPresentation,
        INSSCommandContext __RPC_FAR *pCommand
        )
//
// Event Logging routine goes here.
//
{
  return( S_OK );
}

See Also

INSSEventHandler::GetHandledEvents


NetShow Event Notification and Authorization Data Structures

The structures and enumerations supported for The NetShow Event Notification and Authorization interfaces include the following;

  • NSS_EVENT
  • NSS_EVENT_TYPE


NSS_EVENT

The NSS_EVENT structure is used to pass events to the NetShow Event Notification and Authorization interfaces.

Syntax

typedef struct NSS_EVENT
{
WORD Version; //
NSSEVENT_TYPE Type; // Type of event.
HRESULT hr; // Results of authorization.
} NSS_EVENT

See Also

NSS_EVENT_TYPE


NSS_EVENT_TYPE

The NSS_EVENT_TYPE enumeration defines the type of event sent from the server to the NetShow Event Notification and Authorization interfaces.

Syntax

typedef enum NSS_EVENT_TYPE
{
Reserved1,
NSSE_SKIP_AUTHENTICATION,
NSSE_CONNECT,
NSSE_DISCONNECT,
NSSE_OPEN,
NSSE_CLOSE,
NSSE_PLAY,
NSSE_STOP,
} NSSE_EVENT_TYPE

See Also

NSS_EVENT


Event Notification and Authorization Samples

The NetShow SDK provides three sample components, written in C++, for developing event notification and authorization plug-in components

Sample | Description
Pay-Per-Minute Authorizer | A plug-in component that authorizes a client to stream a title based on a pay-per-minite payment schedule.
Pay-Per-View Authorizer | A plug-in component that authorizes a client to stream a title based on a pay-per-view payment plan.
Memebership Authorizer | A plug-in component that grants permissions to members only to stream a title.

To test the SDK sample, you should have the appropriate ActiveX controls installed in your system. It is recommended that you run these samples on a machine that has NetShow installed. To download the complete suite of NetShow products visit the NetShow web site http://www.microsoft.com/NetShow


Encoder Automation Programming Guide

[This is preliminary documentation and subject to change.]

The Encoder Automation Programming Guide has these parts:

Part | Description
About Encoder Automation | Architecture of the Automation server.
Using Encoder Automation | Guide to using and programming the Automation server.
Encoder Automation Reference | Reference to the Automation server methods and properties.
Automation Client Demo | Sample Microsoft® Visual Basic® code to start the Automation server.
Scripting Utility Sample | A sample Visual Basic utility used to embed script commands into Advanced Streaming format (ASF) streams.


About the Encoder

The Encoder takes audio signals, video signals, and/or script commands, and encodes them into an ASF stream. This stream can then be saved to a file and broadcast by using NetShow™ Server.

The Encoder can be used by an administrator without any programming. However, to automate encoding or run multiple encoders, a programming interface is provided by using Automation.

For more information about using the Encoder as an application, see the NetShow Tools Guide.


Using Encoder Automation

The Encoder exposes a COM IDispatch interface that enables a client application to call methods and properties.

This SDK focuses on client applications written in Microsoft® Visual Basic®. For detailed information on using Microsoft Visual C++® to create an Automation client application, see the Automation Programmer's Reference from Microsoft Press (ISBN 1-57231-584-9). Visual Basic is recommended for most applications because it hides the details of connecting to the IDispatch and other COM interfaces.


Starting the Encoder

To start the Encoder, use the following code in Visual Basic:

Dim Encoder As Object
Set Encoder = CreateObject("Asf.NSASFRte")
Encoder.LoadASD("c:\SampleConfig.asd")
Encoder.Start

The object name of the Encoder is Asf.NSASFRte. Once the object is created for use by Visual Basic, an .asd (Advanced Stream Description) file is loaded that contains all the properties needed by the Encoder to begin encoding. Then the Start method is called, and the encoding begins.


Stopping the Encoder

To stop the Encoder, use the following code:

Encoder.Stop
Set Encoder = Nothing

Setting the object to Nothing releases the object from memory.


Reading Encoder Properties

To read a property, make sure you have already loaded a configuration (using LoadASD) into the Encoder. For example, to read the Description property, use the following code to display the description of the Encoder session in a message box:

MsgBox Encoder.Description


Recording to .asf Files

Use the following code to record to an .asf file:

Encoder.MaxSize = 5000   ' 5 MB file maximum size
Encoder.RecordFileName = "c:\Sample.asf"
Encoder.RecordStart

To stop a recording:

Encoder.RecordStop

You can start and stop a recording at any time during an encoding session.

For more discussion on using the other methods and properties, see the Encoder Automation Reference.


Encoder Automation Reference

The Encoder exposes the following methods and properties through Automation:

  • Encoder Methods
  • Encoder Properties


Encoder Methods

Encoder Automation exposes the following methods:

Method | Description
LoadASD | Loads a configuration into the Encoder from an .asd file.
RecordStart | Starts recording to an .asf file.
RecordStop | Stops recording to an .asf file.
SendScript | Inserts a script command to the ASF stream.
Start | Starts an encoding session.
Stop | Stops an encoding session.


LoadASD Method

Loads an .asd file.

Syntax

NSASFRte.LoadASD( FileName )

Parameters

FileName

A String value specifying the name of the file to be loaded. The extension of the file name must be .asd.

Return Values

This method has no return value.

Remarks

An .asd file is created by the Encoder standalone application to store all attributes of an encoding session. Currently there is no programmatic method for setting configuration attributes or for creating .asd files.


RecordStart Method

Starts recording to an .asf file.

Syntax

NSASFRte.RecordStart

Parameters

This method has no parameters.

Return Values

This method has no return value.

Remarks

Use this method to start recording streaming data to an .asf file. Specify the file name with the RecordFileName property.

After calling this method, recording to the .asf file will continue until the first of the following events occurs:

  • The RecordStop method is called.
  • Encoding is stopped by calling the Stop method.
  • The end of the input file is reached (if a .wav or .avi file is being encoded).
  • The limit set by the RecordMaxSize property is reached.
  • The limit set by the RecordDuration property is reached.

See Also

RecordDuration, RecordMaxSize, RecordSize, RecordStop, IsRecording, RecordFileName,RecordAutoOverride,RecordAutoStart


RecordStop Method

Stops recording to an .asf file.

Syntax

NSASFRte.RecordStop

Parameters

This method has no parameters.

Return Values

This method has no return value.

Remarks

Use this method to stop recording streaming data to an .asf file. Specify the .asf file name with the RecordFileName property.

See Also

RecordDuration, RecordMaxSize, RecordSize, RecordStart, IsRecording, RecordFileName ,RecordAutoOverride,RecordAutoStart


SendScript Method

Inserts a script command into the ASF stream.

Syntax

NSASFRte.SendScript( Type, Text )

Parameters

Type

A String value specifying the type of command.

Text

A String value specifying the command's text.

Return Values

This method has no return value.

Remarks

A script command is associated with a designated time in the ASF stream. When the stream reaches the appointed time, the Microsoft NetShow Player control rendering the stream issues an event. The event can be captured and processed by an event handling routine. Any Type of command can be sent for a reciprocal event handler written for the player to process the command. The following Types of commands are automatically handled by the Player control:

  • URL - Launches the URL in the default browser.
  • FILENAME - Opens the file and begins playing it.

Script commands can only be sent if the AllowScripts property is TRUE.

See Also

AllowScripts


Start Method

Starts an encoding session.

Syntax

NSASFRte.Start

Parameters

This method has no parameters.

Return Values

This method has no return value.

Remarks

Use this method to start an encoding session.

Use the IsStarted property to see whether or not the Encoder is currently running.

If one of the desired output sources is a file, the RecordAutoStart property must be TRUE for the output to be sent to the file automatically when the Start method is called. If the RecordAutoStart property is FALSE, a separate call to RecordStart is necessary to record output to a file.

See Also

IsStarted , Stop, RecordAutoStart ,RecordAutoOverride


Stop Method

Stops an encoding session.

Syntax

NSASFRte.Stop

Parameters

This method has no parameters.

Return Values

This method has no return value.

Remarks

Use this method to stop an encoding session.

Use the IsStarted property to see whether or not the Encoder is currently running.

See Also

IsStarted, Start


Encoder Properties

Encoder Automation exposes the following properties:

Property | Read/Write | Description
AllowAudio | R | Returns a Boolean value specifying whether or not audio can be encoded.
AllowScripts | R | Returns a Boolean value specifying whether or not script commands can be sent.
AllowVideo | R | Returns a Boolean value specifying whether or not video can be encoded.
AudioFormatTag | R | Returns a Long value specifying the audio codec.
AudioSource | R | Returns a BSTR value specifying the audio source.
Bandwidth | R | Returns a Long value specifying the bandwidth.
BitsPerPixel | R | Returns a Short value specifying the color depth for a video image, such as 16 bit or 24 bit.
DelayBuffer | R | Returns a Short value specifying the size of the delay buffer.
Description | R | Returns a BSTR value specifying the description of the Encoder session.
FramesPerSecond | R | Returns a Short value specifying the number of video frames per second.
ImageHeight | R | Returns a Short value specifying the image height in pixels.
ImageWidth | R | Returns a Short value specifying the image width in pixels.
InputSourceFile | R/W | Returns or sets a BSTR value specifying the name of the source file to be encoded.
IPPort | R | Returns a Short value specifying the IP Port.
IsNetEnabled | R | Returns a Boolean value specifying whether or not the Encoder is using the network.
IsRecording | R | Returns a Boolean value specifying whether or not the Encoder is recording to an .asf file.
IsStarted | R | Returns a Boolean value specifying whether or not the Encoder has started.
NetShowServer | R | Returns a BSTR value specifying the name of the Microsoft® NetShow™ server being used for primary distribution.
NumClients | R | Returns a Short value specifying the number of clients connected to the Encoder.
RecordAutoOverride | R/W | Returns or sets a Boolean value indicating whether the Encoder will overwrite a previous file with the same name.
RecordAutoStart | R/W | Returns or sets a Boolean value indicating whether recording to a file begins automatically when the method is called.
RecordDuration | R/W | Returns or sets a Long value specifying the time duration of the file to be recorded.
RecordFileName | R/W | Returns or sets a BSTR value specifying the name of the .asf file that will be created in a recording session.
RecordMaxSize | R/W | Returns or sets a Long value specifying the maximum file size for a recording.
RecordSize | R | Returns a Long value specifying the current size of the file being recorded.
SecondsPerIFrame | R | Returns an Short value specifying the number of seconds before a complete video frame must be sent.
StreamAlias | R | Returns a BSTR value specifying the stream alias used to connect to the NetShow server.
VideoCodecFOURCC | R | Returns a Long value specifying the video codec.
VideoInputFOURCC | R | Returns a Long value specifying the video source.


AllowAudio Property

Returns a Boolean value specifying whether or not audio can be sent.

Syntax

NSASFRte.AllowAudio


AllowScripts Property

Returns a Boolean value specifying whether or not script commands can be sent.

Syntax

NSASFRte.AllowScript


AllowVideo Property

Returns a Boolean value specifying whether or not video can be sent.

Syntax

NSASFRte.AllowVideo


AudioFormatTag Property

Returns a Long value specifying the format of the audio codec.

Syntax

NSASFRte.AudioFormatTag

Remarks

The value returned is either a number representing an audio format or a FOURCC value. For more information about FOURCC, see the VideoInputFOURCC property.

See the Mmreg.h file in the Microsoft® Windows® SDK for a list of supported audio formats.

See the VideoInputFOURCC property for a Microsoft Visual Basic® code sample that will convert a FOURCC value to a human-readable string.

See Also

VideoInputFOURCC


AudioSource Property

Returns a BSTR value specifying the audio source.

Syntax

NSASFRte.AudioSource

Remarks

A typical audio source would be SoundBlaster. Due to inconsistencies in driver names, a name like SoundBlaster can differ between operating systems as well as card types.


Bandwidth Property

Returns a Long value specifying the bandwidth in bits per second.

Syntax

NSASFRte.BandWidth


BitsPerPixel Property

Returns a Short value specifying the bits-per-pixel ratio of a video image.

Syntax

NSASFRte.BitsPerPixel


DelayBuffer Property

Returns a Short value specifying the size of the Encoder's delay buffer.

Syntax

NSASFRte.DelayBuffer

Remarks

The delay buffer is the amount of time (in seconds) allocated to the Encoder for arranging video, audio, and other data samples before the stream can be rendered by the client.


Description Property

Returns a BSTR value specifying the description of the Encoder session.

Syntax

NSASFRte.Description


FramesPerSecond Property

Returns a Short value specifying the number of video frames per second.

Syntax

NSASFRte.FramesPerSecond


ImageHeight Property

Returns a Short value specifying the image height in pixels.

Syntax

NSASFRte.ImageHeight


ImageWidth Property

Returns a Short value specifying the image width in pixels.

Syntax

NSASFRte.ImageWidth


InputSourceFile Property

Returns or sets a BSTR value specifying the name of the source file to be encoded.

Syntax

NSASFRte.InputSourceFile

Remarks

The source file must be an .avi or a .wav file. The Encoder currently accepts input from a file or a live device. However, live input and file input can not be encoded simultaneously.


IPPort Property

Returns a Short value specifying the IP port.

Syntax

NSASFRte.IPPort


IsNetEnabled Property

Returns a Boolean value specifying whether or not the Encoder is using the network.

Syntax

NSASFRte.IsNetEnabled

Remarks

This property is False if the Encoder is recording to an .asf file but is not sending a stream over a network. Use this property to determine whether the IPPort and NetShowServer values are valid.

See Also

IPPort , NetShowServer


IsRecording Property

Returns a Boolean value specifying whether or not the Encoder is recording to an .asf file.

Syntax

NSASFRte.IsRecording

See Also

RecordDuration, RecordMaxSize, RecordStart, RecordStop, RecordFileName, RecordAutoOverride


IsStarted Property

Returns a Boolean value specifying whether or not the Encoder has started.

Syntax

NSASFRte.IsStarted

Remarks

Use the Start and Stop properties to start or stop the Encoder.

See Also

Start , Stop , RecordAutoOverride


NetShowServer Property

Returns a BSTR value specifying the name of the distribution server.

Syntax

NSASFRte.NetShowServer

Remarks

The Encoder allows multiple clients to be connected. This property specifies the name of the station manager server.

See Also

NumClients


NumClients Property

Returns a Short value specifying the number of clients connected to the Encoder.

Syntax

NSASFRte.NumClients


RecordAutoOverride Property

Returns or sets a Boolean value indicating whether the Encoder will overwrite a previous file with the same name.

Syntax

NSASFRte.RecordAutoOverride

Remarks

The default value for this property is FALSE. When the Encoder starts writing to a file that already exists, by default it will stop and return an error. To overwrite the file instead of returning an error, the RecordAutoOverride property should be set to TRUE. The ability to overwrite an existing file is particularly useful when the Encoder is running on a remote computer.

See Also

Start , RecordAutoStart, RecordFileName


RecordAutoStart Property

Returns or sets a Boolean value indicating whether recording to a file begins automatically when the Start method is called.

Syntax

NSASFRte.RecordAutoStart

Remarks

If the value of this property is TRUE, the stream is recorded to an .asf file when Start is invoked.

This property is initialized as follows when the .asd file is loaded:

  • If the RecordFileName property is empty, RecordAutoStart is initialized to FALSE.
  • If RecordFileName is not empty, RecordAutoStart is initialized to TRUE.

After the .asd file is loaded, changes to the RecordFileName property affect RecordAutoStart as follows:

  • If RecordFileName is set to empty, RecordAutoStart is reset to FALSE.
  • If RecordFileName is reset to any value other than empty, RecordAutoStart is not reset. Changing the value of RecordFileName from empty to any other value will not change RecordAutoStart to TRUE.

See Also

Start , IsRecording, RecordFileName , RecordAutoOverride


RecordDuration Property

Returns or sets a Long value specifying the time duration of the file to be recorded.

Syntax

NSASFRte.RecordDuration

Remarks

The value of the time duration is measured in seconds.

Setting this property to zero specifies that no time limit is placed on the file being recorded.

See Also

RecordMaxSize, RecordStart, RecordStop, RecordFileName, IsRecording


RecordFileName Property

Returns or sets a BSTR value specifying the name of the .asf file that will be created in a recording session.

Syntax

NSASFRte.RecordFileName

Remarks

If you change the RecordFileName property while the ASF Encoder is recording an .asf file, an error will occur. If the ASF Encoder is recording and you want to change the name of the .asf file that is being created, you must call RecordStop to stop the recording, set the file name, and then call RecordStart to start recording again.

See Also

RecordDuration, RecordMaxSize, RecordStart, RecordStop, IsRecording, RecordAutoOverride


RecordMaxSize Property

Returns or sets a Long value specifying the maximum file size for a recording.

Syntax

NSASFRte.RecordMaxSize

Remarks

The maximum file size is measured in kilobytes (1024 bytes).

Setting this property to zero specifies that no size limit is placed on the file being recorded.

See Also

RecordDuration, RecordStart, RecordStop, RecordFileName, IsRecording


RecordSize Property

Returns a Long value specifying the current size of the file being recorded.

Syntax

NSASFRte.RecordSize

Remarks

The current file size is measured in kilobytes (1024 bytes).

See Also

RecordDuration, RecordMaxSize, RecordStart, RecordStop, IsRecording, RecordFileName, IsRecording


SecondsPerIFrame Property

Returns a Short value specifying the number of seconds per image frame for video.

Syntax

NSASFRte.SecondsPerIFrame


StreamAlias Property

Returns a BSTR value specifying the stream alias used to connect to the distribution server.

Syntax

NSASFRte.StreamAlias

Remarks

This property shows the stream alias used by the server to connect to the Encoder.


VideoCodecFOURCC Property

Returns a Long value specifying the video codec.

Syntax

NSASFRte.VideoCodeFOURCC

Remarks

FOURCC is an industry-standard format that describes a video or audio format. The number returned is 32-bits; each 8 bits represents a character, and the four characters together describe the format. (Note that the order of the characters is right to left). For example, if the hexadecimal value returned is 0x3336326D, this represents the Microsoft H.263 Video Codec (m263).

See the VideoInputFOURCC property for a Microsoft Visual Basic code sample that will convert a FOURCC value to a human-readable string.

If 0 (zero) is returned, the format is standard RGB.

See Also

VideoInputFOURCC


VideoInputFOURCC Property

Returns a Long value specifying the video input configuration in FOURCC format.

Syntax

NSASFRte.VideoInputFOURCC

Remarks

FOURCC is an industry-standard format that describes a video or audio format. The number returned is 32 bits; each 8 bits represents a character, and the four characters together describe the format (note that the order of the characters is right to left). For example, if the hexadecimal value returned is 0x3336326D, this represents the Microsoft H.263 Video Codec (m263).

The following Microsoft Visual Basic code example converts a FOURCC Long value to a human-readable string:

  HWH = (FOURCC And &HFFFF0000) / &H1000000
  HWL = (FOURCC And &HFF0000) / &H10000
  LWH = FOURCC - (FOURCC And &HFFFF0000)
  LWH = (LWH And &HFF00) / &H100
  LWL = FOURCC - (FOURCC And &HFFFF0000)
  LWL = LWL And &HFF
  FCCS = Chr(LWL) & Chr(LWH) & Chr(HWL) & Chr(HWH)

If 0 (zero) is returned, the format is standard RGB.

See Also

VideoCodecFOURCC


Automation Client Demo

The following sample code can be pasted into a Microsoft Visual Basic application. The code is separated into three parts:

  • Code to start the Encoder is attached to a button named Start.
  • Code to stop the Encoder is attached to a button named Stop.
  • Code to generate a report on the property values is attached to a button named DoReport. The report is displayed in a multiline text box named Report.
  • A control named Encoding becomes visible to indicate that the server is encoding.

Minimal error checking is included.

The following tasks must be completed before the client application can run.

  • The Encoder must be installed.
  • A session must be created and saved to an .asd file named Sample.asd.

Note that the declaration of the Encoder (RTE) object is outside of the private subroutines. The object must be created and started to read the properties.

Dim RTE As Object

Private Sub Start_Click()
  On Error Resume Next
  Set RTE = CreateObject("Asf.NSASFRte")
  If Err.Number Then MsgBox "Object not loaded."
  RTE.LoadASD("c:\Sample.asd")
  If Err.Number Then MsgBox "ASD file not loaded."
  RTE.Start
  Encoding.Visible = True
End Sub

Private Sub Stop_Click()
  On Error Resume Next
  RTE.Stop
  Set RTE = Nothing
  Encoding.Visible = False
End Sub

Private Sub DoReport_Click()
  On Error Resume Next
  If Not RTE.IsStarted Then MsgBox "RTE not running": Exit Sub
  Report.Text = "The Encoder has started."
  Report.Text = Report.Text & vbCrLf & "Description: " & RTE.Description
  Report.Text = Report.Text & vbCrLf & "IP Port: " & RTE.IPPort
  Report.Text = Report.Text & vbCrLf & "AllowScripts: " & RTE.AllowScript
  Report.Text = Report.Text & vbCrLf & "AllowVideo: " & RTE.AllowVideo
  Report.Text = Report.Text & vbCrLf & "AllowAudio: " & RTE.AllowAudio
  Report.Text = Report.Text & vbCrLf & "ImageWidth: " & RTE.ImageWidth
  Report.Text = Report.Text & vbCrLf & "ImageHeight: " & RTE.ImageHeight
  Report.Text = Report.Text & vbCrLf & "FramesPerSecond: " & RTE.FramesPerSecond
  Report.Text = Report.Text & vbCrLf & "SecondsPerIFrame: " & RTE.SecondsPerIFrame
  Report.Text = Report.Text & vbCrLf & "BitsPerPixel: " & RTE.BitsPerPixel
  Report.Text = Report.Text & vbCrLf & "VideoInputFOURCC: " & RTE.VideoInputFOURCC
  Report.Text = Report.Text & vbCrLf & "DelayBuffer: " & RTE.DelayBuffer
  Report.Text = Report.Text & vbCrLf & "AudioFormatTag: " & RTE.AudioFormatTag
  Report.Text = Report.Text & vbCrLf & "AudioSource: " & RTE.AudioSource
  Report.Text = Report.Text & vbCrLf & "VideoCodecFOURCC: " & RTE.VideoCodecFOURCC
  Report.Text = Report.Text & vbCrLf & "Bandwidth: " & RTE.Bandwidth
  Report.Text = Report.Text & vbCrLf & "InputSourceFile: " & RTE.InputSourceFile

  If RTE.IsNetEnabled Then
  Report.Text = Report.Text & vbCrLf & "NetShowServer: " & RTE.NetShowServer
  Report.Text = Report.Text & vbCrLf & "StreamAlias: " & RTE.StreamAlias
  Report.Text = Report.Text & vbCrLf & "NumClients: " & RTE.NumClients
  EndIf

  If RTE.IsRecording Then
  Report.Text = Report.Text & vbCrLf & "RecordDuration: " & RTE.RecordDuration
  Report.Text = Report.Text & vbCrLf & "RecordMaxSize: " & RTE.RecordMaxSize
  Report.Text = Report.Text & vbCrLf & "RecordSize: " & RTE.RecordSize
  Report.Text = Report.Text & vbCrLf & "RecordFileName: " & RTE.RecordFileName
  EndIf

  End Sub


Scripting Utility Sample

One of the features of Microsoft NetShow Advanced Streaming format (ASF) is the ability to embed script commands into the stream. The embedded script commands are two Unicode strings associated with a designated time in the stream. One string specifies the type of command, and the other string contains the actual command. When the stream reaches the time associated with the command, the NetShow Player control issues an event that can be captured and processed by an event handling routine.

Both of the command strings are passed as parameters to the event handler. The type parameter is used to determine how the command parameter should be processed, and the command parameter specifies the action to be performed. For example, commands to launch URLs can be embedded into ASF streams. The type parameter for these commands is URL and the command parameter would contain the URL to be launched by the browser.

The Player control automatically handles the following types of embedded script commands;

  • URL - The specified URL is launched in the default browser.
  • FILENAME - The Player control opens the file specified and plays the stream.

Any type of command can be embedded into an ASF stream, and reciprocal code can be written for the client application to handle the command. Unknown types of commands are ignored by the Player control; however, they are still handed off to the event handling routine for processing.

The Encoder provides a Commands dialog box for embedding script commands into the ASF streams it is producing. Script commands entered into the Commands dialog box are dropped into the stream to be executed by the client application.

The Encoder Commands dialog box does have limitations. Once a command is sent, it is not retained in the Commands dialog box, requiring users to retype the command before it can be sent again. Another drawback is that it can not import commands stored in a script file.

About the Scripting Utility Sample

The scripting utility sample demonstrates how to design a Microsoft Visual Basic utility by using the methods and properties exposed through Automation for embedding script commands. It provides an easy–to-use interface for embedding commands into an ASF stream. The utility provides the following features, which extend the functionality of the standard interface:

  • Importing a text file containing script commands. The imported commands are displayed in a hierarchical list.
  • Sorting the list of script commands.
  • Copying a command from the list into the Commands dialog box by clicking the command. The command can then be edited in the Commands dialog box before it is sent.
  • Keeping a list of the most recently used (MRU) commands for future use.

The utility also incorporates the following features of the Encoder:

  • The ability to import an .asd file.
  • The ability to start and stop the Encoder.
  • A display for viewing the properties of the Encoder while it is running.

Sample Components

The sample components are installed by clicking the link specified below. The following components are downloaded when the sample is installed:

  • The ASF Real-Time Scripting Utility Sample (RTEScript.exe).
  • Sample Web pages for viewing the results, (RTESample.htm, Frame1.htm, and Frame2.htm).
  • The Visual Basic source code used to build the utility.
  • A sample script file (Sample.txt).

Requirements

The sample uses an .asd file containing the settings needed by the Encoder. Currently there is no programmatic way to create an .asd file. Use the Encoder to perform this task. For more information about creating an .asd file to specify the settings, see the Encoder documentation. The .asd file must specify the following settings:

  • The input must be from a live source. This utility will not work with input from .avi or .wav files.
  • The option "Enable Script Commands" must be enabled.
  • The output destination can not be a local .asf file.

To Use the Utility

The steps outlined below demonstrate how to use the utility:

  1. Open the .asd file by clicking the icon on the toolbar or selecting the Open ASD File option from the drop-down File menu. For the utility to work correctly, the .asd file must meet the requirements listed above.

  2. Open the script command file by clicking the icon on the toolbar or selecting the Open Script File option from the drop-down File menu. The syntax for creating script command files is outlined in the “Creating a Sample Script File” section. The commands imported from the file are displayed by a listview control.

  3. Start the Encoder by clicking the Start Encoding button.

  4. Select a command to be sent by clicking the command displayed in the listview control. The command should appear in the Current Command dialog box. Alternatively, commands may be typed directly into this dialog box. Commands can be altered once they are in the dialog box.

  5. When the command appears correctly in the Current Command dialog box, click the Send button. A message is displayed to indicate that the command has been sent. The Current Command dialog box is cleared, and the command that was just sent is added to the 10 most recently used commands.

    No error codes are returned when the script command is sent. The best way to determine if the command was received and processed successfully is by observing the results on a NetShow Player connected to the Encoder. The Web page included with this sample is ideal for testing the output generated from the Encoder. Instructions for using the Web page are outlined below.

  6. To view properties of the Encoder while it is running, select the View ASD File Properties option from the drop down File menu.

Creating a Sample Script File

Any text editor can be used to create a script file used by the scripting utility. The following list outlines the format of a script file:

  • Only one command or comment is allowed per line. A carriage return indicates a new line.
  • The format for a command line is the command type followed by a comma, followed by the command. In addition to the URL and FILE command types that are automatically processed by the Player control, the Web page included with this sample also processes CAPTION and TEXT command types. There are no restrictions on the types of commands that can be sent; however, only URL, FILE, CAPTION, and TEXT will be processed by the sample Web page. Instructions for using the Web page are outlined in the “Viewing Output on the Sample Web Page” section. See the Sample.txt file included with this sample for examples of command lines.
  • Comments are denoted by a semicolon (;) in the first column of the line. See the Sample.txt file included with this sample for examples of comment lines.
  • To specify a destination frame for URL commands, append two ampersands (&&) and the name of the frame to the end of the command.

Viewing Output on the Sample Web Page

The Web page included with the sample uses two frames. One frame (Frame1.htm) contains the embedded player and the other (Frame2.htm) is available for launching URL commands received from the scripting utility. Launching URLs in Frame2 allows the player to continue rendering the stream from the Encoder in Frame 1.

While it is possible to run the sample utility and the Web page on the same computer, running the Encoder and the scripting utility on one computer and the sample Web page on another computer is recommended.

The following list outlines the steps for using the Web page:

  1. Start the Encoder Scripting Utility.

  2. From the utility, open the .asd file and start the Encoder.

  3. Launch the sample Web page from a browser.

  4. Connect the Web page to the ASF Encoder.

  5. Send script commands from the utility and view the results on the Web page.

Troubleshooting

The status bar at the bottom of the sample utility displays whether or not the .asd file is loaded and whether or not encoding has started.

The Start Encoding option remains disabled until a valid .asd file is loaded.

The Send Command button remains disabled until the encoding process starts successfully.

If the Encoder can not be started from the utility ,or script commands are not being processed as expected on the sample Web page, try the following steps:

  1. Stop the Encoder from the scripting utility.

  2. Start the Encoder and open the .asd file that was loaded by the scripting utility.

  3. Try using the Encoder to send script commands.

  4. If the problems persist, check the configuration settings.

  5. Use the Encoder's online Help to troubleshoot the problem and correct the settings.

Installing the Sample

You can download this sample by linking to http://www.microsoft.com/netshow/download/rtescript.exe.

These examples illustrate how to use HTML and the Visual Basic Scripting Edition, with attributes exposed by Microsoft NetShow. They may not be fully functional within the Platform SDK framework. To download the complete suite of NetShow products, which includes working samples, visit the NetShow web site (http://www.microsoft.com/NetShow)


Netshow File Transfer Control

[This is preliminary documentation and subject to change.]

The File Transfer Control section of the Microsoft® NetShow™ SDK is divided into the following segments:

Part | Description
About File Transfer | Architecture of the control.
Using File Transfer | Guide to using and programming the control.
File Transfer Reference | Reference to the control events, methods, and properties.
File Transfer Examples | Sample Web pages using the control.


About File Transfer

The Microsoft NetShow file transfer control is a Microsoft ActiveX® control that allows broadcast files to be received over networks.


Kinds of File Transfers

The file transfer control supports two kinds of file transfer services:

  • Multicast file transfers. One sender transfers files to many receivers over a corporate intranet or the Internet, using multicast addresses and valid unused ports. The receiver "listens" to the same multicast IP address and port to receive the file.
  • Unicast file transfers. One sender transfers files to one receiver over a corporate intranet or the Internet, using non-multicast addresses and valid unused ports. The receiver "listens" to one of its own IP addresses and the same port.


Fully Reliable Service

The file transfer control implements a Fully Reliable service for multicasting, ensuring that each packet sent is received correctly. If the receiver determines that packets are missing or damaged, it can send a negative acknowledgment (NAK) to the sender requesting that the packets be resent.

In the Fully Reliable mode, the file transfer service performs flow control in addition to the rate control done by the sender. If the sender is transmitting packets too fast, the receiver sends a Throttle NAK indicating that the transfer should slow down. The receiver also sends an Idle NAK when it is busy or has not heard from the sender for awhile.

The NetShow file transfer control uses the Fully Reliable service as the default. If the sender does not use the Fully Reliable service, however, the control will still receive transfers, but will not be able to request the retransmission of any missing packets. The Fully Reliable service can be turned off with the FullyReliableService property.

A two-way (bidirectional) network is required for the Fully Reliable service.

The Fully Reliable service requires that forward error-correction (FEC) be used.


Negative Acknowledgement (NAK)

A negative acknowledgement (NAK) is a message sent from the receiver to the sender indicating that packets were dropped. An NAK is a request to resend the packets. Using NAKs is an efficient way to add reliability, because the receiver needs to request only the packets in a sequence that were not received.

NAK requests are part of the Fully Reliable service.


Throttle NAK

A request from the receiver to the sender to reduce bandwidth is known as a throttle negative acknowledgment, or a Throttle NAK.

Throttle NAK requests are part of the Fully Reliable service.


Idle NAK

An idle negative acknowledgment, or Idle NAK, is a request from the receiver to the sender saying that no packets are being received but the transfer is not complete. When a sender gets Idle NAKs from a receiver, it waits to hear from any other receivers, which could still send NAKs requesting packets that need to be resent.

Idle NAK requests are part of the Fully Reliable service.


Receiving Files

To receive a file:

  1. Start the receive operation before the sender starts sending to insure that all files will be transferred. If the receiver starts after the sender has begun sending a group of files, the receiver will receive the current file and all subsequent files. If only one file is being sent and the receive operation starts in the middle of the transfer, the file will be received.

  2. Start a receive operation with the FtsCancelFileTransferReceive method on the computer on which you want to receive the file(s). This is called listening.
    • For multicast transfers, use a multicast address.
    • For unicast transfers, specify one of the host computer's local addresses. If no local address is specified, the first local address on the host computer will be used as a default.
  3. Wait until the file is sent by the sender.

The receiver can cancel a file transfer with the FtsCancelFileTransferReceive method.

Status and progress of the transfer can be read through events and properties during the file transfer and at the transfer completion. See Notifications for information about status and notifications.


Notifications

The File Transfer object can notify the receiver of the status and progress of a file transfer by using events.


Status Notification

The status of a file transfer is communicated to the receiver through events. Events are triggered only if a notification request for that event is made by using the FtsRegisterStatusCallback method. The following events are triggered by a change in the file transfer status, but only if the proper notification has been made with the FtsRegisterStatusCallback:

Event | Description
FtsOnTransferStarted | Triggered by the start of an entire transfer operation.
FtsOnTransferCompleted | Triggered by the completion of an entire file transfer operation.
FtsOnFileTransferStarted | Triggered by the start of an individual file transfer operation.
FtsOnFileTransferCompleted | Triggered by the completion of an individual file or directory structure transfer operation.
FtsOnStatusChanged | Triggered by a change in the status of a transfer.

When an event is triggered, you can read information about the status of an event through the appropriate properties. Read the properties in an event subroutine and take appropriate action.


Progress Notification

To receive progress statistics about an ongoing file transfer, register the kind of transfer information you want with the FtsRegisterStatusCallback method. Typical kinds of requests would be to notify the caller every 100KB of the file transfer or every 10 percent of the file transfer. Notifications can also be requested about the number of packets received, as well as the number of bogus packets (received on the same IP address and port, but not part of an expected file transfer operation), duplicate packets, dropped packets, and so on. Progress notifications are processed by the FtsOnTransferProgress event. Read the appropriate properties and take the appropriate action in an FtsOnTransferProgress subroutine. You can revoke a progress notification by calling the FtsRevokeStatusCallback method.

Note that progress notifications trigger only the FtsOnTransferProgress event. The values of transfer progress properties (such as NumPacketsDropped) are continuously available.


Further Information

For more information about developing applications with the NetShow file transfer control, see Using File Transfer.

For a reference to the NetShow file transfer events, methods, and properties, see File Transfer Reference.

For examples of how to use this control on a Web page, see File Transfer Examples.


Using File Transfer

Microsoft® NetShow™ file transfer uses an ActiveX control to receive files by using multicast routing. See the Microsoft ActiveX SDK for more information about ActiveX controls.

In the interest of simplicity, this tutorial focuses on using a scripting language, such as Microsoft Visual Basic® Scripting Edition, to explain how to use the control. See the Visual Basic Script home page for more information about Visual Basic Scripting Edition (VBScript). See the Microsoft ActiveX SDK for more ways to use ActiveX controls. For example, the Microsoft ActiveX Control Pad is used for rapid application development using ActiveX controls.


Sample Application

By using a scripting language such as VBScript, it is easy to receive complex file transfers by using multicast routing over the Internet or corporate intranets.


HTML Shell

Use the following HTML shell for your application to create a Web page.

<HTML>
<HEAD>
<TITLE>NetShow File Transfer</TITLE>
</HEAD><BODY>
</BODY>
</HTML>


Add Object Information

Add the following object information to the <BODY> section of the document. This tells the browser what object to load. The object must be loadable by the browser.

<OBJECT ID="NSFile" WIDTH="100" HEIGHT="51"
CLASSID="CLSID:26F24A93-1DA2-11D0-A334-00AA004A5FC5"
CODEBASE="http://www.microsoft.com/netshow/download/en/nsftsinf.cab#Version=2,0,0,888">
</OBJECT>

Note that ID and CLASSID are required. CODEBASE is recommended to make sure you have the correct version.

Make sure that the version number matches the version you want to specify. The version given above may not be the latest version of the file transfer control.


Adding the Form

Add the appropriate form elements to create the user interface for your Web application. Typical elements include buttons for user input and text boxes to provide information to the user.


Adding the Scripting Code

For this SDK, VBScript is used. First you must notify the browser which scripting language you intend to use, and then include the scripted commands in a comment. Put the SCRIPT tag anywhere in the BODY and embed the comment-surrounded code within the SCRIPT tags. The code will respond to events on the Web pages, such as clicking, and call methods on the file transfer control. The code will also respond to file transfer events and allow the application to read information about the file transfer, take appropriate action, and notify the user about the status and progress of the transfer.

<SCRIPT LANGUAGE="VBScript">
<!--...-->
</SCRIPT>


General Notes

For general information about ActiveX controls, see the Microsoft ActiveX SDK.

For more information about using VBScript with ActiveX controls, see the Visual Basic Script home page.

Note For testing multicast file transfers, it is recommended that you test in networks that are completely multicast-enabled, and do not use tunneling

For more information about the architecture of the file transfer control, see About File Transfer.

For a reference to the file transfer methods, see File Transfer Reference


File Transfer Reference

List of File Transfer Events

List of File Transfer Methods

List of File Transfer Properties

Note The prefix Fts on events and methods stands for File Transfer Service, the technology used in NetShow file transfer. This service is not a Microsoft Windows NT® "service" and can be used on Microsoft Windows® 95 or Windows NT version 4.0 for receiving files.


File Transfer Events

The following events are attached to the File Transfer object:

Event | Description
FtsOnTransferStarted | Triggered by the start of an entire transfer operation.
FtsOnTransferCompleted | Triggered by the completion of an entire file transfer operation.
FtsOnFileTransferStarted | Triggered by the start of an individual file transfer operation.
FtsOnFileTransferCompleted | Triggered by the completion of an individual file or directory structure transfer operation.
FtsOnTransferProgress | Triggered by a requested progress notification.
FtsOnStatusChanged | Triggered by a change in the status of a transfer.


FtsOnTransferStarted Event

This event is triggered by the start of an entire transfer operation.

Syntax

NSFile_FtsOnTransferStarted

Parameters

This event has no parameters.

Remarks

After this event is triggered, you can read properties to get information on the file transfer and take appropriate action.


FtsOnTransferCompleted Event

This event is triggered by the completion of an entire file transfer operation.

Syntax

NSFile_FtsOnTransferCompleted

Parameters

This event has no parameters.

Remarks

The following code example shows how to use FtsOnTransferCompleted to notify the user how many bytes were transferred. The File Transfer object is NSFile and the code in the subroutine will be called when a file transfer completed event is triggered. The code gets the number of bytes from the NumTotalBytesTransferred property and displays it to the user.

Sub NSFile_FtsOnTransferCompleted
   MsgBox nsfile.NumTotalBytesTransferred
End Sub


FtsOnFileTransferStarted Event

This event is triggered by the start of an individual file transfer operation.

Syntax

NSFile_FtsOnFileTransferStarted

Parameters

This event has no parameters.


FtsOnFileTransferCompleted Event

This event is triggered by the completion of an individual file transfer operation.

Syntax

NSFile_FtsOnFileTransferCompleted

Parameters

This event has no parameters.


FtsOnTransferProgress Event

This event is triggered by a requested progress notification.

Syntax

NSFile_FtsOnTransferProgress

Parameters

This event has no parameters.

Remarks

Register the notifications you want with the FtsRegisterStatusCallback method.

The following kinds of progress notifications will trigger this event. Each item represents a requested increment of file transfer (for example, specifying 4096 for the number of total bytes would trigger a progress notification every 4096 bytes of the entire file transfer).

  • Number of file data bytes
  • Percent of file data bytes
  • Number of total data bytes
  • Number of total bytes
  • Number of packets
  • Number of packets dropped
  • Number of packets corrected
  • Number of bogus packets
  • Number of duplicate packets


FtsOnStatusChanged Event

This event is triggered by a change in the status of a transfer.

Syntax

NSFile_FtsOnStatusChanged

Parameters

This event has no parameters.

Remarks

The following code example shows how to use FtsOnStatusChanged to determine that a transfer was canceled. The File Transfer object is NSFile and the code in the subroutine will be called when the status of a file transfer changes. The change in this case is that a file transfer has "completed" (TransferStatus = 5) because it was canceled (Result = -2147467260).

Sub NSFile_FtsOnStatusChanged
   Canceled = (nsfile.TransferStatus = 5) And (nsfile.Result = -2147467260)
    If Canceled Then MsgBox &quot;Transfer was canceled.&quot;
End Sub


File Transfer Methods

The following methods are attached to the File Transfer object:

Method | Description
FtsStartFileTransferReceive | Starts a file transfer receive operation.
FtsCancelFileTransferReceive | Cancels an ongoing file transfer receive operation.
FtsRegisterStatusCallback | Registers a status callback.
FtsRevokeStatusCallback | Revokes a registered status callback.


FtsStartFileTransferReceive

FtsStartFileTransferReceive Method

Starts a file transfer receive operation.

Syntax

NSFile.FtsStartFileTransferReceive( SrcAddr, Port Filter, DestPath, Attrib Flags )

Parameters

SrcAddr

The Internet Protocol (IP) address of the intended source. You must use a string that consists of four numbers separated by periods. Each of the four numbers must be a number from 0 through 255. A typical address would be 239.4.7.54. If a null string ("") is entered, then the first local address is used. Typically this would be entered if the caller wanted to receive by unicast. Also, for unicast transfers, the host name or local address can be entered.

Port

Sets the IP port. You must use a number from 1 through 65535.

Filter

Sets the file path filter, allowing the receiver to specify filter paths. You must use a string that can be resolved into a file path. Note that paths can include environment variables (such as %TEMP%) or wild cards (such as * and ?). This parameter is typically used to match files to determine which files to receive. For example, if the pattern *.avi were used, only the files with an .avi extension would be copied.

DestPath

Sets the path of the intended destination. You must use a string that can be resolved into a file path. Note that paths can include environment variables (such as %TEMP%) or wild cards (such as * and ?). The receiver can override the desired destination by using this parameter. This parameter is typically used for renaming files or choosing a specific directory. For example, specifying *.avi would rename all received file extensions to .avi. Do not supply a value for this parameter if you intend to receive URLs for cache-stuffing.

Attrib

Sets the filter attributes of the files to be copied. If 0 (zero) is specified, then no filtering is performed. The following numbers are valid and may be combined for multiple attributes. For example, a file can be read-only and hidden and would have the numeric value of 3.

Value | Description
0 | The file or directory has no other attributes set. This attribute is valid only if used alone.
1 | The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
2 | The file or directory is hidden. It is not included in an ordinary directory listing.
4 | The file or directory is part of, or is used exclusively by, the operating system.
16 | The "file or directory" is a directory.
32 | The file or directory is an archive file or directory. Applications use this flag to mark files for backup or removal.
256 | The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
2048 | The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
4096 | The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.

Flags

Sets the manner in which copied files are created on the destination. If 0 (zero) is specified, the defaults are chosen. Note that the defaults are chosen based on the type of address and port (for example, a multicast address default would include forward error-correction). The following numbers are valid and may be combined for multiple flags. For example, if you wanted to continue on error and copy directory structures only, the numeric value would be 24. Starting out with a value of 1 is required if you are receiving files from the Microsoft® NetShow™ Administrator application (you can add flag values to this number), since this application sends files by using forward error-correction. In addition, adding the flag value of 1024 (asynchronous receive) is recommended so that your receive application will not "freeze" while receiving.

Decimal Value | Description
1 | Use forward error-correction ( FEC). This flag is required for multicast transfers that are sent using the NetShow Administrator application. The transfer expected by the receiver was sent using forward error-correction. Redundant information is sent so that if no more than a specified percentage of the packets is lost, the file will still be copied. If this flag is set and a connection-oriented transfer (for example, TCP) is attempted, this method will return E_INVALIDARG. FEC is meant for connectionless transfers such as UDP.
2 | Create a file even if an error occurs in the transfer process. Note that this should be used only by applications that can process potentially corrupt files.
4 | Copy hidden and system files.
8 | Continue on error. Continue transfer operation even if an error occurs in the copying of one file in a group of files.
16 | Copy directory structure only; do not copy files.
32 | Overwrite destination files even if the read-only bit is set.
64 | Copy only if the file exists in the destination directory.
128 | Copy source files depending on whether the source file date is later than the date on the destination file.
256 | Copy all attributes of the source file to the destination file. If this flag is not set, the read-only attribute will be reset.
512 | Copy using short names (8.3 characters) only.
1024 | Copy asynchronously. This flag is recommended for multicast transfers that are sent using the NetShow Administrator application. If this flag is not set, the browser will "freeze" until the transfer is completed. If an application can spawn threads, it can receive synchronously without "freezing." This flag (asynchronous) is recommended for scripting languages.
2048 | Copy only if the copy does not overwrite files.
4096 | Destination path is a file. If the file received is a directory and this flag is set, E_FAIL will be returned; the transfer will not take place, and Result will not be set.
8192 | Destination path is a directory. If the file received is a file and this flag is set, E_FAIL will be returned; the transfer will not take place, and Result will not be set.
16384 | Receive files continuously. If set, this flag will result in the File Transfer Service receiving files continuously until either the transfer is cancelled by the sender or receiver or there is a fatal error (for example, E_OUTOFMEMORY). The object would keep receiving if the individual receive calls return S_OK or non-fatal errors like STG_E_FILENOTFOUND. This flag should be set only if the asynchronous flag is also set. Otherwise the transfer call will fail and an E_INVALIDARG error message will be generated. If this flag is set and all the arguments are valid, the File Transfer object will loop until the transfer is explicitly cancelled. If the receiver starts to receive files continuously but then wants to cancel and start over, the FtsOnTransferCompleted event should be processed to make sure that the cancel has taken place. Also, if this flag is set, a notification request for a completed transfer should be registered, so that if the transfer is cancelled by the sender, the receiver can continue receiving by starting another receive operation with a new File Transfer object. However, if this flag is set, the receiver will never time out. In addition, if this flag is set, the File Transfer object will also set the continue on error flag. Note that in continuous mode, once the FTS loops back and starts another listen, all statistical properties (bytes, packets, and so on) are reset. To retrieve statistical properties for each transfer, you should register for an FtsOnTransferCompleted callback and check the statistics in that subroutine. In non-continuous mode, the statistical properties are not reset after the transfer, so you can check the statistics after the transfer completes, as long as you don't start a new transfer before reading the statistics.
32768 | Do not merge flags. The default behavior is to combine (bitwise OR) the flags of the sender and receiver and resolve all conflicts in favor of the receiver. If the receiver does not set this flag, this allows the sender to specify flags than can be resolved only by the receiver (for example, copy only newer files).
65536 | Copy source subdirectories to destination subdirectories. This flag is set implicitly if either the copy directory structure only or copy empty directories flags are set.
131072 | If a file with the archive bit set is copied, reset the archive bit after copying.
262144 | Copy empty directories

Return Values

This method does not return a value. However, it does return a Microsoft COM HRESULT error code to the Microsoft Visual Basic® Script Error object.

The following codes are passed to the Error object:

Decimal Value | Description (HRESULT)
0 | The request to start a receive operation was successful. (S_OK) Note that a transfer can start successfully, but may later fail. The Result property should be read when a transfer is completed to make sure that no error occurred after the transfer started.
-2147467260 | Transfer was canceled. The cancel could have come from the sender or the receiver. (E_ABORT) To determine whether the receiver or the sender cancelled the transfer, the receiver could set a variable whenever it cancels a transfer.
-2147467259 | The request to receive could not take place for an unspecified reason.(E_FAIL)
-2147287038 | The request to receive could not take place because a file was not found or no file was found that matched a filter. (STG_E_FILENOTFOUND)
-2147024882 | The request to receive could not take place because the File Transfer object was out of memory. (E_OUTOFMEMORY)
-2147024809 | The request to receive could not take place because an invalid argument was supplied. (E_INVALIDARG)
-2147023436 | The request to receive could not take place because the receiver timed out. (ERROR_TIMEOUT converted to an HRESULT)
-2147023840 | The request to receive could not take place because the file transfer service is busy with another transfer. (ERROR_SERVICE_ALREADY_RUNNING converted to an HRESULT)

Remarks

To receive a multicast transfer, enter a multicast address for the source address. For multicast addresses, the first number in the IP address string should be from 224 through 239 (that is, range from 224.0.0.0 through 239.255.255.255). Addresses starting with 239 are usually reserved for corporate intranets and are not passed beyond a firewall. Do not use an address from 224.0.0.0 through 224.0.0.255, as those addresses are reserved for multicast session announcements.

To receive a unicast file transfer, enter a null string ("") for the source address and enter an appropriate port number. For example, if a null string is entered for the source address and port 2000 is specified, the receiver will start listening on the first local address and on port 2000.

When neither the "destination path is a file" nor the "destination path is a directory" flag is set, the File Transfer object will use the following logic to determine whether a file or directory will be created on the destination.

If the intended destination is ... | and the actual destination has... | then the following will be created ...
A file named "A" | No file of the same name | A file named "A"
A directory named "B" | No directory of the same name | A directory named "B"
A file named "A" | A directory named "A" | A file named "A" will be created inside the directory named "A"
A directory named "B" | A file named "B" | A file named "B." Every file that would have been in directory "B" will be copied to the filename "B." The last file copied will be the contents of the file "B."

Note that for the sender, wild cards are used to create collections of files and directories, so any ambiguity on the destination will be resolved in favor of directories. For the receiver, wild cards are used for matching, so any ambiguity on the destination will be resolved in favor of files. In general, the caller should specify exactly what he or she wants created on the destination, especially if he or she cannot be sure what files and directories will be on the destination.


FtsCancelFileTransferReceive Method

Cancels an ongoing file transfer receive operation.

Syntax

NSFile.FtsCancelFileTransferReceive

Parameters

This method has no parameters.

Return Values

This method does not return a value. However, it does return a Microsoft COM HRESULT error code to the Microsoft® Visual Basic® Script Error object.

The following codes are passed to the Error object:

Decimal Value | Description (HRESULT)
0 | The action requested was successful. (S_OK)
1 | The action requested cannot take place because the transfer has not started or has already completed. (S_FALSE).
-2147467259 | The action requested could not take place for an unspecified reason.(E_FAIL).

Remarks

A transfer cannot be cancelled if it has already completed or has been defined but is not yet in operation.


FtsRegisterStatusCallback Method

Registers a transfer notification request callback. Each parameter is independent, and more than one kind of request can be sent in a single call to this method. Putting 0 (zero) in a parameter indicates that you do not want to be notified for that particular kind of request. Each unique collection of parameter values makes up a separate notification request. If the caller wants to revoke the request, each unique collection of parameter values must be used in the call to FtsRevokeStatusCallback.

When a requested notification occurs, the corresponding event is triggered. By placing code that reads the appropriate properties in the corresponding subroutine, you can process the transfer notification.

Syntax

NSFile.FtsRegisterStatusCallback( Cur, Per, Data, Tot, Pack, Drop, Corr, Bogus, Dup, Flags, Param )

Parameters

Cur

Number of file data bytes that will transfer before each notification occurs. Does not include file header bytes or other non-data file information such as redundancy bytes. For example, specifying 8192 would trigger an FtsOnTransferProgress notification for every 8KB of file data bytes transferred.

Per

Percent of file data bytes that will transfer before each notification occurs. Does not include file header bytes or other non-data file information such as redundancy bytes. For example, specifying 10 would trigger an FtsOnTransferProgress notification for every 10 percent of the file data bytes transferred.

Data

Total data bytes (for all files requested) that will transfer before each notification occurs. Does not include file header bytes or other non-data file information such as redundancy bytes. For example, specifying 8192 would trigger an FtsOnTransferProgress notification for every 8KB of file data bytes transferred, even if this included more than one file.

Tot

Total bytes (for all files requested) that will transfer before each notification occurs, including file header bytes or other non-data file information such as redundancy bytes. For example, specifying 8192 would trigger an FtsOnTransferProgress notification for every 8KB of file bytes transferred, even if this included more than one file.

Pack

Number of packets that will transfer before each notification occurs. For example, specifying 100 would trigger an FtsOnTransferProgress notification for every 100 packets transferred

Drop

Number of packets that are dropped before each notification occurs. For example, specifying 50 would trigger an FtsOnTransferProgress notification for every 50 packets dropped.

Corr

Number of packets that are corrected before each notification occurs. For example, specifying 25 would trigger an FtsOnTransferProgress notification for every 25 packets received and corrected.

Bogus

Number of bogus packets that are received before each notification occurs. For example, specifying 25 would trigger an FtsOnTransferProgress notification for every 25 bogus packets received. A bogus packet is a packet that is received on the same IP address and port as the receiver is listening for, but which is not part of an expected file transfer operation. For example, this would happen if a file transfer were taking place and the receiving address started getting audio packets on the same address.

Dup

Number of duplicate packets that are received before each notification occurs. For example, specifying 5 would trigger an FtsOnTransferProgress notification for every five duplicate packets received.

Flags

The following flags are used by this method to define the type of notification requested. Multiple flags can be used on each request. If 0 (zero) is specified, the File Transfer object would default to a "transfer completed" notification (the same value as 8).

Value | Description
0 | Notification requested for a completed transfer operation (same as 8).
4 | Notification requested for the start of a transfer operation.
8 | Notification requested for a completed transfer operation (same as 0).
16 | Notification requested for the start of each individual file transfer operation.
32 | Notification requested for a completed transfer operation for each individual file.
64 | Notification requested for any change in the status of the file transfer.

Param

A parameter used by the caller to identify different calls. The content is arbitrarily chosen by the caller. Any Long number is valid.

Return Values

This method does not return a value. However, it does return a Microsoft COM HRESULT error code to the Visual Basic Script Error object.

The following codes are passed to the Error object:

Decimal Value | Description (HRESULT)
0 | The action requested was successful. (S_OK)
1 | The action requested is already taking place. (S_FALSE)
-2147467259 | The action requested could not take place for an unspecified reason.(E_FAIL)
-2147024882 | The action requested could not take place because the File Transfer object was out of memory. (E_OUTOFMEMORY)
-2147024809 | The action requested could not take place because an invalid argument was supplied. (E_INVALIDARG)

Remarks

For asynchronous transfers, it is recommended that a default notification be registered before calling FtsStartFileTransferReceive. The default call for an object named object would be:

call object.FtsRegisterStatusCallback(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)

File transfer notifications have an internal granularity. For example, if 100 bytes at a time are transferred, and the caller requests notification every 10 bytes, the caller will be notified only every 100 bytes. The granularity of each type of notification is implementation-specific.

The caller will always receive a notification even if the increment of change is larger than that requested. For example, if the caller requests notification every 10 bytes, and a 45-byte file is sent, the caller will receive five notifications. Or if the caller requests notification every 100 bytes and only 10 bytes are sent, the caller will receive one notification.

This method registers callbacks for the progress and changes of status of a file transfer operation. Progress notifications are processed by FtsOnTransferProgress . Status notifications are processed by FtsOnStatusChanged, as well as the status-specific events such as FtsOnTransferStarted, FtsOnTransferCompleted, FtsOnFileTransferStarted, and FtsOnFileTransferCompleted.

Notification callbacks do not have to be revoked. When the File Transfer object shuts down, all notifications are also destroyed.


FtsRevokeStatusCallback Method

Revokes a registered transfer progress notification request callback. To revoke a specific status callback, you must match the pattern of parameters that was used to request the callback. For example, if a call was made with FtsRegisterStatusCallback(0,10,0,0,0,0,0,0,100,0,0), which would request a notification for every 10 percent of the data bytes of the file transfer as well as for every 100 duplicate packets received, that particular notification can be revoked only by the matching call: FtsRevokeStatusCallback(0,10,0,0,0,0,0,0,100,0). Note that FtsRegisterStatusCallback has 11 parameters and FtsRevokeStatusCallback has only 10. The revoke does not use the Param parameter.

Syntax

NSFile.FtsRevokeStatusCallback( Cur, Per, Data, Tot, Pack, Drop, Corr, Bogus, Dup, Flags )

Parameters

Cur

Number of file data bytes that will transfer before each notification occurs. Does not include file header bytes or other non-data file information such as redundancy bytes. For example, specifying 8192 would revoke an FtsOnTransferProgress notification for every 8K of file data bytes transferred.

Per

Percent of file data bytes that will transfer before each notification occurs. Does not include file header bytes or other non-data file information such as redundancy bytes. For example, specifying 10 would revoke an FtsOnTransferProgress notification for every 10 percent of the file data bytes transferred.

Data

Total data bytes (for all files requested) that will transfer before each notification occurs. Does not include file header bytes or other non-data file information such as redundancy bytes. For example, specifying 8192 would revoke an FtsOnTransferProgress notification for every 8K of file data bytes transferred, even if this included more than one file.

Tot

Total bytes (for all files requested) that will transfer before each notification occurs, including file header bytes or other non-data file information such as redundancy bytes. For example, specifying 8192 would revoke an FtsOnTransferProgress notification for every 8K of file bytes transferred, even if this included more than one file.

Pack

Number of packets that will transfer before each notification occurs. For example, specifying 100 would revoke an FtsOnTransferProgress notification for every 100 packets transferred.

Drop

Number of packets that are dropped before each notification occurs. For example, specifying 50 would revoke an FtsOnTransferProgress notification for every 50 packets dropped.

Corr

Number of packets that are corrected before each notification occurs. For example, specifying 25 would revoke an FtsOnTransferProgress notification for every 25 packets received and corrected.

Bogus

Number of bogus packets that are received before each notification occurs. For example, specifying 25 would revoke an FtsOnTransferProgress notification for every 25 bogus packets received. A bogus packet is a packet that is received on the same IP address and port as the receiver is listening for, but is not part of an expected file transfer operation. For example, this would happen if a file transfer were taking place and the receiving address started getting audio packets on the same address.

Dup

Number of duplicate packets that are received before each notification occurs. For example, specifying 5 would revoke an FtsOnTransferProgress notification for every five duplicate packets received.

Flags

The following flags are used by this method to define the type of notification request you want to revoke. Multiple flags can be used on each revoke request. If 0 (zero) is specified, the File Transfer object would default to a "transfer completed" notification (the same value as 8).

Value | Description
0 | Notification revoked for a completed transfer operation (same as 8).
4 | Notification revoked for the start of a transfer operation.
8 | Notification revoked for a completed transfer operation (same as 0).
16 | Notification revoked for the start of each individual file transfer operation.
32 | Notification revoked for a completed transfer operation for each individual file.
64 | Notification revoked for any change in the status of the file transfer.

Return Values

This method does not return a value. However, this object does return a Microsoft COM HRESULT error code to the Visual Basic Script Error object.

The following codes are passed to the Error object:

Decimal Value | Description (HRESULT)
0 | The action requested was successful. (S_OK)
1 | The action requested is already taking place. (S_FALSE)
-2147467259 | The action requested could not take place for an unspecified reason. (E_FAIL)
-2147024809 | The action requested could not take place because an invalid argument was supplied. (E_INVALIDARG)


File Transfer Properties

The following properties are attached to the File Transfer object. Properties can be read or written. There are no write-only properties. Properties that are read-only are marked "R" in the table below. Properties that are read or write are marked "R/W" in the table below.

Property | Read/Write | Description
Result | R | Returns the result of a file transfer operation.
TransferOperation | R | Returns the transfer operation for File Transfer object.
TransferStatus | R | Returns the status of the File Transfer object.
Param | R | Returns a value used by the caller to identify different transfer notification requests.
NumDirectoriesTransferred | R | Returns the number of directory structures transferred.
NumFilesTransferred | R | Returns the number of files transferred.
PercentFileDataBytesTransferred | R | Returns the percentage of file data bytes transferred.
NumTotalBytesTransferred | R | Returns the total bytes for all files transferred.
NumTotalDataBytesTransferred | R | Returns the total data bytes for all files transferred.
NumFileDataBytesTransferred | R | Returns the number of file data bytes transferred for the current file.
CurrentFilePath | R | Returns the current file path.
CurrentFileAttributes | R | Returns the attributes of the current file.
CurrentFileSize | R | Returns the size of the current file.
NumPacketsTransferred | R | Returns the number of packets transferred.
NumPacketsDropped | R | Returns the number of packets dropped.
NumPacketsCorrected | R | Returns the number of packets received and corrected.
NumBogusPacketsReceived | R | Returns the number of bogus packets received.
NumDuplicatePacketsReceived | R | Returns the number of duplicate packets received.
AddressFamily | R/W | Returns or sets the address family of the File Transfer object.
Type | R/W | Returns or sets the type of File Transfer object.
Protocol | R/W | Returns or sets the protocol of the File Transfer object.
LocalAddress | R/W | Returns or sets the local address of the File Transfer object.
ReceiveTimeout | R/W | Returns or sets the receive timeout of the File Transfer object.
MaxReceiveBufferSize | R/W | Returns or sets the maximum receive buffer size of the File Transfer object.
LocalPort | R/W | Returns or sets the local port of the File Transfer object.
SourceFilePath | R | Returns the source file path of the file transfer.
DestinationFilePath | R | Returns the destination file path of the file transfer.
EndpointAddress | R | Returns the endpoint address of the file transfer.
EndpointPort | R | Returns the endpoint port of the file transfer.
SourceAddress | R | Returns the source address of the file transfer.
SourcePort | R | Returns the source port of the file transfer.
ValidateReceivedPackets | R/W | Returns or sets a value that indicates whether the user wants to validate incoming packets to ensure that they are for the current transfer.
LocalPortUsed | R | Returns the local port used for the last file transfer.
FullyReliableService | R/W | Returns or sets the status of the Fully Reliable service.
FullyReliableServiceUsed | R | Returns a value indicating whether or not a transfer is using the Fully Reliable service.

Remarks

If a file transfer has not started, read-only transfer progress properties will return a value of -1 for numeric properties and a null string ("") for string properties. If a transfer starts but then fails before any transfer takes place, read-only transfer progress properties will return a value of 0 for numeric properties and a null string ("") for string properties. These latter null values indicate that a transfer was initiated, but did not actually start.


Result Property

Returns the result of a file transfer. The number returned corresponds to a Microsoft® COM HRESULT error code.

Syntax

NSFile.Result

Return Values

The Result property returns these values:

Decimal Value | Description (HRESULT)
0 | Transfer was a success. (S_OK)
-2147467260 | Transfer was cancelled. The cancel could have come from the sender or the receiver. (E_ABORT)
-2147467259 | Transfer failed. (E_FAIL)
-2147287038 | File not found or no file is found that matches a wild card or filter. For example, if the receiver expects a file named "fremont.avi" and the sender sends "ballard.avi", this error is returned. (STG_E_FILENOTFOUND)
-2147024882 | Out of memory. (E_OUTOFMEMORY)
-2147024809 | Invalid argument provided to a method or property. (E_INVALIDARG)
-2147023436 | The transfer failed because the receiver timed out. (ERROR_TIMEOUT converted to an HRESULT)

Remarks

The Result property returns the results of a transfer. Method calls return the result of the method call, which may not be the same error message as Result. For example, a method call to start the receive operation may return S_OK, but the transfer may return E_OUTOFMEMORY when the transfer is completed. It is recommended that the return value of a method call be checked for errors when the call is made, and that the Result parameter be checked when the transfer is completed.

If invalid parameters are entered for a method and the transfer has not yet started, the Result property will not be set. If invalid arguments are entered and a transfer has already started, the Result property will be set.

The Result property applies only to the last transfer. When a new transfer begins, the Result property is reset.

If an error occurs during a transfer, the caller should query NumFilesTransferred and NumDirectoriesTransferred to find out how many files and directory structures were transferred before the transfer failed.

Unknown error message values from Microsoft Windows® are passed through the control and converted to HRESULT values. To convert a Microsoft Win32® system error, you must have the Win32 SDK and the latest copy of the Winerror.h file. To convert from an HRESULT to a Winerror.h value, subtract the hexadecimal value of 0x80070000 from the returned error and convert to decimal.


TransferOperation Property

Returns the transfer operation for the File Transfer object.

Syntax

NSFile.TransferOperation

Return Values

The TransferOperation property returns these values.

Value | Description (HRESULT)
0 | The file transfer object is not in operation.
2 | The file transfer object is in operation. It is ready to receive, it is receiving, or it has finished receiving.

Remarks

Do not use TransferOperation to determine the status of a transfer. Use TransferStatus or the file transfer events to determine transfer status.


TransferStatus Property

Returns the status of the ile transfer object.

Syntax

NSFile.TransferStatus

Return Values

The TransferStatus property returns these values.

Value | Description (HRESULT)
0 | A transfer has been defined, but is not yet in operation.
1 | A transfer is preparing to operate.
2 | A receiver is listening (waiting for data).
3 | A transfer is in progress.
5 | A transfer is completed.

Remarks

Changes in the value of the TransferStatus property indicate that the status of the transfer object has changed. Any change of the status of the transfer object triggers the FtsOnStatusChanged event. If any other events coincide with a change in the transfer status, they will be triggered also. For example, the completion of a file transfer would trigger FtsOnTransferCompleted.

Note that transfer progress notification callbacks operate independently of the status notifications, even when a status notification is requested by the callback. See FtsRegisterStatusCallback for more information about transfer progress notifications.


Param Property

Returns the parameter of the transfer progress notification registered by the FtsOnTransferProgress event that has triggered the most recent transfer notification event.

Syntax

NSFile.Param

Remarks

The parameter can be used by the caller to identify different transfer notification requests. The value can be arbitrarily chosen by the caller. Any Long number is valid.

For example, a caller could identify the first FtsOnTransferProgress request with a param parameter value of 4, the second request with 7, and the third request with 54. Then when a notification event is triggered, the Param property can be read. In this example, if the Param property value were 54, that would indicate that it was the third request that triggered the event.


NumDirectoriesTransferred Property

Returns the number of directories transferred. This includes only the number of directory structures transferred and does not include the contents of the directories.

Syntax

NSFile.NumDirectoriesTransferred


NumFilesTransferred Property

Returns the number of files transferred.

Syntax

NSFile.NumFilesTransferred


PercentFileDataBytesTransferred Property

Returns the percentage of file data bytes transferred. It does not include file header bytes or other non-data file information such as redundancy bytes. The range is from 0 through 100 decimal.

This property is always available after a transfer has started.

Syntax

NSFile.PercentFileDataBytesTransferred


NumTotalBytesTransferred Property

Returns the total bytes for all files currently transferred, including file header bytes or other non-data file information such as redundancy bytes.

When forward error-correction (FEC) is used, the number of bytes transferred will be larger than the file size. For example, if a FEC of 20 percent is used, the NumTotalBytesTransferred value will be approximately 20 to 40 percent larger than the file size.

This property is always available after a transfer has started.

Syntax

NSFile.NumTotalBytesTransferred


NumTotalDataBytesTransferred Property

Returns the total data bytes for all files transferred currently. It does not include file header bytes or other non-data file information such as redundancy bytes.

This property is always available after a transfer has started.

Syntax

NSFile.NumTotalDataBytesTransferred


NumFileDataBytesTransferred Property

Returns the number of file data bytes transferred for the current file. It does not include file header bytes or other non-data file information such as redundancy bytes.

This property is always available after a transfer has started.

Syntax

NSFile.NumFileDataBytesTransferred


CurrentFilePath Property

Returns the path of the current file. For example, if a series of files is being sent, the current file is the file that is currently being received.

Syntax

NSFile.CurrentFilePath

Remarks

For URL transfers, the current URL will be returned.


CurrentFileAttributes Property

Returns the attributes of the current file.

Syntax

NSFile.CurrentFileAttributes

Return Values

The following numbers are valid and may be combined for multiple attributes. For example, a file can be read-only and hidden and would have the numeric value of 3.

Value | Description (HRESULT)
0 | The file or directory has no other attributes set. This attribute is valid only if used alone.
1 | The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
2 | The file or directory is hidden. It is not included in an ordinary directory listing.
4 | The file or directory is part of, or is used exclusively by, the operating system.
16 | The "file or directory" is a directory.
32 | The file or directory is an archive file or directory. Applications use this flag to mark files for backup or removal.
256 | The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
2048 | The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
4096 | The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.


CurrentFileSize Property

Returns the size (in bytes) of the current file.

Syntax

NSFile.CurrentFileSize


NumPacketsTransferred Property

Returns the number of packets transferred.

Syntax

NSFile.NumPacketsTransferred

Remarks

The value returned refers to valid (that is, non-bogus) packets only. See NumBogusPacketsReceived.

This property is always available after a transfer has started.


NumPacketsDropped Property

Returns the number of packets dropped.

Syntax

NSFile.NumPacketsDropped

Remarks

This property is always available after a transfer has started.


NumPacketsCorrected Property

Returns the number of packets received and corrected.

Syntax

NSFile.NumPacketsCorrected

Remarks

This property is always available after a transfer has started.


NumBogusPacketsReceived Property

Returns the number of bogus packets received. A bogus packet is a packet that is received on the same IP address and port the receiver is listening for, but which is not part of an expected file transfer operation. For example, this could happen if a file transfer were taking place and the receiving address started getting audio packets on the same address.

Syntax

NSFile.NumBogusPacketsReceived

Remarks

If one protocol is expected and another is received, the packets received will be considered bogus packets. For example, if forward error-correction (FEC) is expected but only non-FEC packets are received, those packets will be tagged as bogus.

This property is always available after a transfer has started.


NumDuplicatePacketsReceived Property

Returns the number of duplicate packets received.

Syntax

NSFile.NumDuplicatePacketsReceived

Remarks

This property is always available after a transfer has started.


AddressFamily Property

Returns or sets the address family of the File Transfer object.

Syntax

NSFile.AddressFamily

Remarks

The address family helps define the network protocol that is used. Address families are defined in the Microsoft® Windows® Sockets documentation. The default value of this property is 2, which corresponds to the standard Internet address family (AF_INET). For example, 6 would correspond to the IPX address family, 11 would correspond to the SNA address family, and 23 would correspond to the proposed Internet version 6 address family. The typical value will be 2, the standard Internet address family. The values of this property are defined in the Winsock2.h header file, which is provided in the Microsoft Win32® SDK.

This property is always available.


Type Property

Returns or sets the socket type of the File Transfer object.

Syntax

NSFile.Type

Return Values

Value | Description (HRESULT)
1 | Corresponds to SOCK_STREAM as defined in the Winsock2.h header file provided by the Microsoft® Win32® SDK.
2 | Corresponds to SOCK_DGRAM as defined in the WINSOCK.H header file provided by the Win32 SDK.

Remarks

This property is always available.


Protocol Property

Returns or sets the protocol family of the file transfer object. The default value is 0 (zero).

Syntax

NSFile.Protocol

Remarks

This property is always available.

Since Microsoft® Windows® Sockets currently defines the protocol family to be the same as the address family, the default value of this property is 0 (zero). If your protocol family does not match the address family, you must set the protocol family as defined in the Winsock2.h header file provided in the Win32 SDK.


LocalAddress Property

Returns or sets the local address of the File Transfer object. The default value is the first local address on the host computer. The "first" local address is configuration specific if the computer has more than one network card. This could be an IP address (for example, 42.4.7.54, or a host name such as "Laure").

Syntax

NSFile.LocalAddress

Remarks

This property is always available.

If no local address is specified, the first local address is chosen and would be returned if the LocalAddress property is read

For more information about the values of this property, see the Microsoft® Windows Sockets documentation.


ReceiveTimeout Property

Returns or sets the receive time-out of the File Transfer object, in milliseconds. The default is three minutes (180,000 milliseconds).

Syntax

NSFile.ReceiveTimeout

Remarks

Extremely large files may need a longer time-out value.

This property is always available.

For more information about the values of this property, see the Microsoft® Windows Sockets documentation.


MaxReceiveBufferSize Property

This property returns or sets the maximum receive buffer size of the File Transfer object, in bytes. The default is 0 (zero), which indicates that the caller does not want a maximum receiver buffer size.

Syntax

NSFile.MaxReceiveBufferSize

Remarks

Specifying the default value of 0 (zero) lets the receive buffer grow to the limits of the amount of virtual memory on the computer. Specifying a non-zero number sets the maximum number of bytes that the receive buffer can grow to.

This property is always available.

For more information about the values of this property, see the Microsoft® Windows Sockets documentation.


LocalPort Property

Returns or sets the local port of the File Transfer object. The default is 0 (zero); that is, any valid, unused port.

Syntax

NSFile.LocalPort

Remarks

This property is always available.

If the LocalPort value is 0, any unused valid port would be chosen once the transfer has started. The caller can then check which local port was chosen by checking the LocalPort property again after the transfer has started.

In order to avoid resetting the LocalPort to 0 after a read, use the LocalPortUsed property to see which port was used for a file transfer.

For more information about the values of this property, see the Microsoft® Windows Sockets documentation.


SourceFilePath Property

Returns the source file path of the file transfer.

Syntax

NSFile.SourceFilePath

Remarks

This property is available after at least one file transfer.


DestinationFilePath Property

Returns the destination file path of the file transfer.

Syntax

NSFile.DestinationFilePath

Remarks

This property is available after at least one file transfer.


EndpointAddress Property

Returns the endpoint address of the file transfer.

Syntax

NSFile.EndpointAddress

Remarks

This is the same address that is passed in as the source address parameter of the FtsStartFileTransferReceive method.

For multicast transfers, this property indicates the multicast address that the receiver is listening to. The receiver can use the SourceAddress property to determine the address of the sender.

For a unicast transfer, this property will return a string specifying the first local address on the host computer.

This property is available after at least one file transfer.


EndpointPort Property

Returns the endpoint port of the file transfer.

Syntax

NSFile.EndpointPort

Remarks

This is the same port that is passed as the port of the receiver that calls the FtsStartFileTransferReceive method.

For multicast transfers, this property indicates the multicast port that the receiver is listening to. The receiver can use the SourcePort property to determine the port of the sender.

For unicast transfers, this property indicates the port that the receiver is listening to.

This property is available after at least one file transfer.


SourceAddress Property

Returns the source address of the file transfer.

Syntax

NSFile.SourceAddress

Remarks

This property can be used to determine the IP address of the sender. One of the uses of this property is to ensure that the source you received a transfer from is the correct source. This property can be useful both as a security measure to validate multicast sources, and to sort out transfers from more than one source. Note that the EndpointAddress property in a multicast transfer indicates the multicast address that the receiver is listening to, not the sender's address.

This property is available after at least one file transfer.

The following example shows how to add minimal security to a multicast file transfer. The file transfer control is named nsfile. When the Transfer Started event is triggered, a check is made to see whether the source address is the one expected (239.4.7.54). If it is not, then a subroutine (StopTransfer) is called that cancels the transfer and notifies the user.

Sub NSFile_FtsOnTransferStarted
 If Not (nsfile.SourceAddress = "239.4.7.54") Then StopTransfer
End Sub
...
Sub StopTransfer
 nsfile.FtsCancelFileTransferReceive()
 MsgBox "The transfer has been cancelled. Wrong source address."
End Sub


SourcePort Property

Returns the source port of the file transfer.

Syntax

NSFile.SourcePort

Remarks

This property can be used to determine the IP port of the sender. One of the uses of this property is to ensure that the source you received a transfer from is the correct source. This property can be useful both as a security measure to validate transfer sources, and also to sort out transfers from more than one source. Note that the EndpointAddress property in a multicast transfer indicates the multicast port that the receiver is listening to, not the sender's port.

This property is available after at least one file transfer.


ValidateReceivedPackets Property

Returns or sets a Boolean value that indicates whether the user wants to validate incoming packets for connectionless transfers (for example, UDP or UDP with forward error-correction) to ensure that they are for the current transfer. Packets that do not pass the validation test are considered bogus packets. The number of bogus packets received can be read through the NumBogusPacketsReceived property. For connection-oriented transfers (for example, TCP), this property is ignored and packets are never validated.

Syntax

NSFile.ValidateReceivedPackets

Remarks

This property should be set to False only if the caller wants the highest level of performance and is willing to risk robustness of the transfer, or the caller has a known private multicast address and port combination that no one else could use. It is highly recommended that this property not be set to False.

This property is set to True by default.

This property is always available.


LocalPortUsed Property

Returns the local port used in the last file transfer.

Syntax

NSFile.LocalPortUsed

Remarks

This property can be used to determine the IP port of the local computer. Note that the LocalPort property returns the local port of the computer before a transfer starts.

This property would typically be used if the LocalPort property were set to 0 (zero), indicating that any valid unused port is to be chosen for the receive. To find out which port was actually used, read the LocalPortUsed property. If LocalPort was set to a non-zero value, then LocalPortUsed is the same as LocalPort.

This property is available after at least one file transfer.


FullyReliableService Property

Returns or sets a Boolean value that indicates whether the user wants to receive a transfer that uses the Fully Reliable service.

Syntax

NSFile.FullyReliableService

Remarks

The Fully Reliable service enables fully reliable file transfers. When packets in a file transfer sequence are missing or bad, the receiver sends requests to the sender to resend the missing or bad packets.

In order to use the Fully Reliable service, forward error-correction (FEC) must be used. Make sure that the Flags parameter of the FtsStartFileTransferReceive method includes the FEC value of 1. Except for making sure that FEC is used when a receive operation is started, the Fully Reliable service is used automatically unless the FullyReliableService property is set to False.

This property is set to True by default. However, if a transfer is received that was sent without using the Fully Reliable service, the control will still receive the transfer but will not attempt to request missing packets and the FullyReliableServiceUsed property value will not change state.

This property is always available.

See Also

FullyReliableServiceUsed


FullyReliableServiceUsed Property

Returns a Boolean value indicating whether or not a transfer is using the Fully Reliable service.

Syntax

NSFile.FullyReliableServiceUsed

Remarks

The FullyReliableService property lets the receiver know whether or not to send NAKs to the sender. However, it does not guarantee that the sender is operating in the fully reliable mode. The receiver may be sending NAKs but the transfer takes place in an unreliable mode if the sender is not operating in the fully reliable mode. The FullyReliableServiceUsed property returns TRUE only if both the sender and the receiver are actually operating in a fully reliable mode.

See Also

FullyReliableService


File Transfer Examples

The following samples show how to use the File Transfer Service. All of the samples require a specific IP address and port for a NetShow server. To use these samples, you will need to modify the address and port so that they point to the server from which you will receive the files.

Sample | Description
Receive Multicast with Cancel and Error-Checking | This sample demonstration shows how to receive a multicast file using the File Transfer Service, using error-checking.
Receive Multicast with Progress | This sample demonstration shows how to receive a multicast file using the File Transfer Service, displaying progress and transfer statistics.
Receive Multicast with Sender Verification | This sample demonstration receives a multicast, and verifies the sender.
Receive Unicast | This sample demonstration shows how to receive files from a unicast server, using the File Transfer Service.
Total Demo | This sample rolls the features of the other samples into one unified demonstration.

These samples demonstrate using HTML and Visual Basic® Scripting Edition, with attributes exposed by Microsoft NetShow FTS control. These samples will not be fully functional without installing the NetShow server. To download the complete suite of NetShow products visit the NetShow web site (http://www.microsoft.com/NetShow)


Microsoft NetShow Theater Server Administration SDK

Microsoft® NetShow™ Theater exposes the Server Administration SDK to facilitate the development of high bandwidth multimedia streaming applications. Using this SDK, it is a simple task to write Web- or Microsoft Windows®-based applications to take advantage of the various NetShow Theater services and to interact with its server components for performing an assortment of tasks, including:

  • Configuring and administering the NetShow Theater servers.
  • Monitoring multiple NetShow Theater server configurations.
  • Monitoring events triggered by a NetShow Theater server.
  • Managing lists of content titles.
  • Managing client connections.

In addition, the SDK allows you to

  • Customize user interfaces for administering the NetShow Theater server. You can automate the UI to fit the needs of novice users, or enable complex functionality for advanced users.
  • Integrate NetShow Theater server streaming capabilities with other applications.
  • Create customized administration and content management solutions for your targeted business: for example, corporate training courses, hospitality, and entertainment services for hotels, cruise ships, and airlines.

The NetShow Theater Server Administration SDK documentation is organized by the Microsoft ActiveX® controls it exposes. For each control a brief introduction is first presented to illustrate how to use the SDK programmatically. The discussion is then followed by a detailed presentation of the related API references. Samples and code excerpts are provided to demonstrate the techniques used to create applications built on the NetShow Theater platform.

Note: The term Theater Server refers to one or more computers, incorporating the title server and up to fourteen content servers. It is also referred to as the Video Server.


About the NetShow Theater Server Administration SDK

The NetShow Theater Server Administration SDK consists of five ActiveX controls: MediaServer, ServerView, ClientView, TitleView, and TraceView. All the controls are packaged in a single .ocx file (Nstadmin.ocx) that comes with the product. In addition, the MediaServer control maintains a set of objects for representing and managing clients, servers, titles, and disk drives.

ActiveX controls are convenient and efficient for creating either Windows- or Web-based applications. You can use these controls in any applications written in Microsoft Visual Basic®, Microsoft Visual C++®, Microsoft Visual J++—, or a combination of HTML and Microsoft Visual Basic Scripting Edition (VBScript) or JavaScript.

This document focuses on developing applications by using Visual Basic and VBScript. Many of the concepts discussed in the SDK assume the reader has some knowledge of the Microsoft Visual Basic version 5.0 development environment, or expertise in using HTML and VBScript. For more information about developing applications by using ActiveX controls, visit the Microsoft Active Platform site, www.microsoft.com/activeplatform. Information about ActiveX scripting languages can be found at the Microsoft VBScript home page, www.microsoft.com/vbscript.


Theater Server Administration Controls

The ActiveX controls exposed in the NetShow Theater Server Administration SDK can be classified into the following two categories:

  • The MediaServer control: This control supports an extensive set of properties, methods, and events for performing administrative tasks.
  • The View controls: These controls provide a graphical user interface for monitoring and managing lists of clients, titles, and events. The View controls are:
    • ClientView control: This control dynamically lists clients connected to the server and the title they are playing.
    • ServerView control: This control displays a tree view of one or more servers and their content servers and content disks.
    • TitleView control: This control lists information about each of the titles available on the server.
    • TraceView control: This control displays a list of notifications of state changes (events) occurring on the server. Events listed by this control include server, client, administration, and alert events.

Along with the Windows Media Player control, the Administration controls can be used to create client applications for creating end-to-end high bandwidth multimedia streaming solutions. For example, they can be used to obtain and display a list of titles available on a title server. The user could select a title from the list and play it using the Windows Media Player.

Note: The Windows Media Player SDK is installed as part of the NetShow Theater SDK setup.


Using Theater Server Administration Controls

This section of the SDK outlines the steps for embedding the controls in a Web page and using the controls in the Visual Basic development environment.


Embedding the Controls in a Web Page

The HTML <OBJECT> tag is used to embed ActiveX controls into a Web page. For controls with a graphical user interface, such as the view controls, the <OBJECT> tag is inserted where you want the control to appear on your page. Controls without a user interface, such as the MediaServer control, can be inserted anywhere within the <BODY> and </BODY> tags.

Following is an example of using the <OBJECT> tag to insert the MediaServer control in a Web page.

<OBJECT CLASSID="clsid:ADB3EC9B-1820-11D1-B062-0000C040BCDB"
             ID=MediaServer
       CODEBASE="nstadmin.ocx#Version=3.0.0.1330">
</OBJECT>

In this example, the <OBJECT> tag has only three attributes:

  • CLASSID: This attribute is used to instantiate an instance of an ActiveX control by assigning to it the Global Class Identifier (CLSID) of the control. Here we intend to launch the MediaServer control. The following table presents the CLSIDs of all the NetShow Theater Server Administration Controls.
    Control | Class ID
    MediaServer | ADB3EC9B-1820-11D1-B062-0000C040BCDB
    ClientView | CE0CD7C0-3B6C-11D1-A40A-00600831F336
    ServerView | 66E9EFF1-36DD-11D1-A5FE-00AA00BF93E3
    TitleView | 1E1BAAB1-3614-11D1-A5FE-00AA00BF93E3
    TraceView | F8B8F885-1FF6-11D1-85F8-0000F8040045

  • ID: The name used to specify the instance of the control. This is the name of the object when it is accessed by a script.
  • CODEBASE: Specifies a URL to the control if it is not on the user's system. Optionally, it can also specify the version number of the control. This attribute is not required; however, it is strongly recommended.

Controls with user-interfaces also require HEIGHT and WIDTH attributes to specify dimensions, in pixels, of the controls.


Installing the Controls in Microsoft Visual Basic

Visual Basic 5.0 provides you with visual tools to install ActiveX controls into your project. To have all the controls installed, you simply bring up the Component dialog box from the Project menu or right click on the Toolbox pane. Then scroll down the Controls panel to select the NetShow Theater Administration Controls. The selected item corresponds to the NSTAdmin.ocx file and contains the MediaServer, ServerView, ClientView, TitleView, and TraceView controls. The controls will show up as five icons in the Toolbox pane.


Distributing Theater Server Administration Applications

Distributing applications created by using this SDK requires loading and registering the following files on the target computer:

  • NSTAdmin.ocx
  • Msrvobj.dll
  • Mmsprxy.exe
  • Mmsprxyps.dll
  • Nslstctl.dll
  • Any walker (file conversion utility) files you wish to use.

These files are installed and registered during SDK setup. By default, they are located in the Program Files\Microsoft NetShow\Theater\Admin folder.

Your setup program should copy these files to the computer running your application, and register the DLLs by using the Regsvr32.exe utility. For Mmsprxy.exe, however, you should use the “Mmsprxy.exe /RegServer” command to register the application.


Programming Guide to the NetShow Theater MediaServer Control

The MediaServer control exposes properties and methods, and supports events used to perform content management and administration tasks on title and content servers. MediaServer control functionality includes:

  • Managing and monitoring client connections to the Title Server.
  • Supervising connections between the Title Server and Content Servers.
  • Managing Content Server disk drives.
  • Managing NetShow Theater titles.
  • Setting bandwidth and bit rate configurations.


MediaServer Component Objects

In addition to the methods, properties, and events used for configuring and managing Theater servers, the MediaServer control also manages collections of component objects that encapsulate the status and behavior of clients, servers, disk drives, and titles. Some objects represent a collection of other objects. These component objects are:

  • A Client object encapsulates the state of a client. It contains the ID of the client, its IP address, the title, if any, being streamed to the client, and the name of its host computer.
  • A Clients object is a collection of Client objects. As with all the collections, you can retrieve a Client member object by using its Item property and query the total number of Client objects by using the Count property. You can also remove a Client object by calling its Remove method.
  • A ContentServer object encapsulates the state of a content server. It holds information about its identifier, the content disk drives it manages, the host computer it is running on, and its working status. A content server is accessible through its associated ContentServer object.
  • A ContentServers object represents a collection of ContentServer objects. It can contain from one to fourteen such objects.
  • A content server Disk object provides access to a content server disk drive dedicated for multimedia content storage. You can query the ID, its drive letter, the disk size, and the status, with the appropriate properties. You can take the disk online or offline by invoking its Online method and repair the content on the disk by calling its Rebuild method.
  • A content server Disks object represents a collection of Disk objects. You can retrieve a member Disk object with the Item property and query the total number of member Disk objects with the Count property. Each ContentServer object manages a Disks collection.
  • A Title object encapsulates the information about a multimedia title, including its description, author, copyright, size, version, format, play duration, and creation time.
  • A Titles collection object contains a number of Title objects. You can call its Add or Remove method to add a title to or remove one from the title server and the Titles collection.
  • A Walker object encapsulates the information about file walker utilities used in the conversion of title format.
  • A Walkers collection object contains a number of Walker objects. In addition to exposing the Item and Count properties, it offers the Find functionality for searching a Walker object by matching its format type.
  • A Logging object exposes methods and properties for managing event log monitoring applications.

The following chart illustrates the hierarchy of objects managed by the MediaServer control:

Using MediaServer Component Objects

As with any object model, you access the methods and properties with the “dot” operator, as illustrated in the following syntax:

<MediaServer Object>.<Component Object>.<Property Name>

For example, you could use

Mediaserver1.Logging.Directory

to access the Directory property of a Logging object.

Using MediaServer Collections

A collection helps to centralize the management of its member objects. All NetShow Theater collection objects are zero-based arrays of like types of objects. All collection objects expose the Count property, which specifies the number of objects contained in the collection, and the Item property for retrieving individual objects in the collection.

To access properties and methods of objects in a collection, the name of the collection object is referenced, with a numeric argument specifying the position of the object in the array. For example, you can use the following syntax to access the Name property of a Client object.

<MediaServer Object>.<Collection Name>[.Item](Index).<Property Name>

The Item property is the default property of each collection object. Explicit use of it to reference a member object is optional. For example, you could write the following code to display the IPAddress property of each Client object in a Clients collection object:

Dim clients as IMSrvClients
Set clients = MediaServer1.Clients
For i=0 to clients.Count-1
  MsgBox clients(i).IPAddress
Next

However, with Visual Basic, you could make the implementation more efficient by using the For Each … In … loop statement:

Dim client As IMSrvClient
For Each client In MediaServer1.Clients
    MsgBox client.ipaddress
Next


NetShow Theater MediaServer Control Reference

The MediaServer ActiveX control encapsulates methods, properties, and events that you can use to write applications to offer NetShow Theater services. The control also enlists a set of objects to perform specific tasks. The following tables summarize the methods, properties, and events, as well as objects supported or manipulated by the MediaServer control.


MediaServer Control Methods

The MediaServer Control supports the following methods:

Method | Description
KillClient | Disconnects a client from NetShow Theater.
SetServer | Connects to a NetShow Theater server and optionally specifies a different server for NetShow Monitor Services.


MediaServer.KillClient Method

The MediaServer.KillClient method disconnects a client from NetShow Theater.

Syntax

MediaServer.KillClient( clientID )

Parameter

ClientID

A Long value specifying the identifier of the client to be disconnected. The value of this parameter corresponds to the Id property of a Client object implementing the IMSrvClient interface.

See Also

Client.ID, OnClientConnect, OnClientDisconnect, OnClientPlay, OnClientStop, OnClientStride


MediaServer.SetServer Method

The MediaServer.SetServer method connects the control to a NetShow Theater server.

Syntax

MediaServer.SetServer( serverName [, eventProxy])

Parameter

serverName

A String value as the name of the title server.

eventProxy

An optional String value specifying the name of the server running NetShow Monitor Service. By default, it is set to the title server.


MediaServer Control Properties

The MediaServer control has the following properties.

Access | Access | Description
BlockMaxBytes | R | Returns a Long value specifying the maximum number of bytes in a block.
BlockPlayTime | R | Returns a Double value specifying the time, in seconds, for a NetShow Theater block.
Clients | R | Returns a collection of the currently active NetShow Theater clients.
Cservers | R | Returns a collection of the NetShow Theater content servers.
Decluster | R | Returns a Long value specifying the number of disks that participate in the distribution of a block’s backup data. This corresponds to the mirror factor.
FreeStorage | R | Returns a Double value specifying the available storage, in bytes.
Fullname | R | Returns a String value specifying the path and name of the NetShow Theater Administrator control.
IsConnected | R | Returns a Boolean value specifying whether an object is still connected to a NetShow Theater server.
Logging | R | Returns an IMSrvLogging object for the logging configuration of the server.
MaxBandWidthProperty | RW | Returns or sets a Double value specifying the currently configured maximum bandwidth, in bits per second, for a particular NetShow Theater Server.
MaxClients | RW | Returns or sets a Long value specifying the maximum number of allowable concurrent streaming and striding clients that can connect to the NetShow Theater Server.
MaxLicensedClients | R | Returns a Long value specifying the maximum number of the licensed viewers on this server.
MaxOpenTitles | R | Returns a Long value specifying the maximum number of titles that can be concurrently streamed and stridden from NetShow Theater.
MaxPhysicalBandWidth | R | Returns a Double value specifying the maximum bandwidth, in bits per second, on a given NetShow Theater server.
MaxStorage | R | Returns a Double value specifying the total storage capacity, in bytes, of NetShow Theater.
MaxStoredTitles | R | Returns a Long value specifying the maximum number of titles that can be stored on NetShow Theater.
MaxTitleBitRate | R | Returns a Long value specifying the maximum bandwidth, in bits per second, of titles.
MinTitleBitRate | R | Returns a Long value specifying the minimum bandwidth, in bits per second, of titles.
NumCServers | R | Returns a Long value specifying the number of content servers in a NetShow Theater system.
NumDisks | R | Returns a Long value specifying the number of content server disks in a NetShow Theater system.
NumStreamingClients | R | Returns a Long value specifying the current number of clients playing content.
OpenTitles | R | Returns a Long value specifying the number of currently opened titles
Server | R | Returns a String value specifying the name of the currently connected NetShow Theater server.
ServerStatus | R | Returns the current operational status of the server, as defined in MSRVSTATUS.
Titles | R | Returns a Titles collection, implementing the IMSrvTitles interface, of the titles on NetShow Theater.
Version | R | Returns a String value specifying the NetShow Theater server version identifier.
Walkers | R | Returns a Walkers collection, implementing the IMSrvWalkers interface, of the installed title walkers in NetShow Theater.


BlockMaxBytes Property

The MediaServer.BlockMaxBytes property returns a Long value specifying the maximum number of bytes in a block.

Syntax

MediaServer.BlockMaxBytes


BlockPlayTime Property

The MediaServer.BlockPlayTime property returns a Long value specifying the time, in seconds, it takes NetShow Theater to stream one block.

Syntax

MediaServer.BlockPlayTime

Remarks

BlockPlayTime is typically 1 second. All blocks in a video server have the same block play time.


Clients Property

The MediaServer.Clients property returns a collection object of all the currently active NetShow Theater clients.

Syntax

MediaServer.Clients

Example

MediaServer1.SetServer "myServer"
MsgBox "There are" & MediaServer1.Clients.Count & " clients on line"

See Also

Clients object


CServers Property

The MediaServer.CServer property returns a collection object of the content servers in the NetShow Theater system.

Syntax

MediaServer.CServers

Example

MediaServer1.SetServer "myServer"
MsgBox MediaServer1.CServers.Count & " content servers on line."

See Also

Content Servers object


Decluster Property

Property

The MediaServer.Decluster property returns a Long value specifying the number of disks that participate in the distribution of backup data of a data block.

Syntax

MediaServer.Decluster

Remarks

The Decluster property corresponds to the mirror factor set during the setup of the NetShow Theater Server.


FreeStorage Property

The MediaServer.FreeStorage property returns a Double value specifying the available storage, in bytes, of all content server disks.

Syntax

MediaServer.FreeStorage

Remarks

The underlying APIs return a 64-bit integer value, but because Visual Basic does not support 64-bit data types, the value is converted to Double.

See Also

MaxStorage


Fullname Property

The MediaServer.Fullname property returns a String value specifying the path to the ActiveX control (Nstadmin.ocx) containing the MediaServer object.

Syntax

MediaServer.FullName


IsConnected Property

The MediaServer.IsConnected property returns a Boolean value specifying whether or not this MediaServer object is connected to a NetShow Theater server.

Syntax

MediaServer.IsConnected


Logging Property

The MediaServer.Logging property returns an object, implementing the IMSrvLogging interface, which contains logging configurations.

Syntax

MediaServer.Logging


MaxBandwidth Property

The MediaServer.MaxBandwidth property returns or sets a Long value specifying the currently configured maximum aggregate bandwidth, in bits per second, for a particular NetShow Theater system.

Syntax

MediaServer.MaxBandwidth

See Also

MaxTitleBitRate, MinTitleBitRate, MaxPhysicalBandwidth, OnMaxBandwidth


MaxClients Property

The MediaServer.MaxClients property returns or sets a Long value specifying the maximum number of clients than can connect to the NetShow Theater Server.

Syntax

MediaServer.MaxClients

Remarks

If the newly assigned value for the maximum number of clients is less than the number of currently connected ones, this method will not disconnect any existing client, but will prevent any new connections.

Striding means streaming without scheduling. A client strides a title when it activates fast-forward or rewind.

See Also

KillClient, Clients object, OnMaxClients


MaxLicensedClients Property

The MediaServer.MaxLicensedClients property returns a Long value specifying the maximum number of viewers licensed to use this server.

Syntax

MediaServer.MaxLicensedClients


MaxOpenTitles Property

The MediaServer.MaxOpenTitles property returns a Long value specifying the maximum number of titles that can be concurrently streamed and stridden from the NetShow Theater Server.

Syntax

MediaServer.MaxOpenTitles

Remarks

Striding means streaming without scheduling. When a client strides a title, it executes fast-forward or rewind.


MaxPhysicalBandWidth Property

The MediaServer.MaxPhysicalBandwidth property returns a Long value specifying the maximum possible aggregate bandwidth, in bits per second, for a particular title server.

Syntax

MediaServer.MaxPhysicalBandwidth

See Also

MaxBandwidth


MaxStorage Property

The MediaServer.MaxStorage property returns a Double value specifying the total storage capacity, in bytes, of the NetShow Theater server.

Syntax

MediaServer.MaxStorage

Remarks

The underlying APIs return a 64-bit integer value, but because Visual Basic does not support 64-bit data types, the value is converted to Double.

See Also

FreeStorage


MaxStoredTitles Property

The MediaServer.MaxStoredTitles property returns a Long value specifying the maximum number of titles that can be stored on a NetShow Theater server.

Syntax

MediaServer.MaxStoredTitles


MaxTitleBitRate Property

The MediaServer.TitleBitRate property returns a Long value specifying the maximum bandwidth, in bits per second, that any single title can have.

Syntax

MediaServer.MaxTitleBitRate

See Also

MinTitleBitRate


MinTitleBitRate Property

The MediaServer.MinTitleBitRate property returns a Long value specifying the minimum bandwidth in bits per second that any single title can have.

Syntax

MediaServer.MinTitleBitRate

See Also

MaxTitleBitRate


NumCServers Property

The MediaServer.NumCServers property returns a Long value specifying the number of content servers in a NetShow Theater system.

Syntax

MediaServer.NumCServers

See Also

NumDisks


NumDisks Property

The MediaServer.NumDisks property returns a Long value specifying the number of content server disks in a NetShow Theater system.

Syntax

MediaServer.NumDisks

Remarks

There are always an integral number of disks per content server. All content servers have the same number of disks.

See Also

NumCServers


NumStreamingClients Property

The MediaServer.NumStreamingClients property returns a Long value specifying the number of clients currently streaming and striding content.

Syntax

MediaServer.NumStreamingClients

Remarks

When a client strides a title, it fast-forwards or rewinds the content.


OpenTitles Property

The MediaServer.OpenTitles property returns a Long value specifying the number of titles that are currently open.

Syntax

MediaServer.OpenTitles


Server Property

The MediaServer.Server property returns a String value specifying the name of the currently connected title server.

Syntax

MediaServer.Server


ServerStatus Property

The MediaServer.ServerStatus property returns a MSRVSTATUS status of the title server.

Syntax

MediaServer.ServerStatus


Titles Property

The MediaServer.Titles property returns a collection object of the titles on a NetShow Theater Server.

Syntax

MediaServer.Titles( titlespec )

Parameters

titlespec

A String specification to match title names, such as "*.vod".

Remarks

The Titles property is unique in that it can accept a titlespec parameter. You can use this feature to obtain a Titles collection of a specified type of titles.

Example

MediaServer1.SetServer "MyServer"
Dim title As IMSrvTitle
For Each title In MediaServer1.Titles("*.vod")
   MsgBox "Title Name:" & title.Name
Next


Version Property

The MediaServer.Version property returns a Long value specifying the version of the NetShow Theater server.

Syntax

MediaServer.Version


Walkers Property

The MediaServer.Walkers property returns a Walkers collection object of the installed title walkers in a NetShow Theater server.

Syntax

MediaServer.Walkers

Example

Sub enumWalkers(server As String)
    Dim walker As IMSrvWalkerEntry
    'NOTE: you must connect to a NetShow Theater Server first
    ‘      in order to enumerate walkers.
    MediaServer1.SetServer server
    For Each walker In MediaServer1.Walkers
        MsgBox walker.Extensions
    Next
End Sub


MediaServer Control Events

Events supported by the MediaServer control are divided into the following categories:

  • Server Events

    These events are fired in response to activities performed by the title and content servers.

  • Administration Events

    These events are fired in response to administration activities.

  • Client Events

    These events are fired in response to clients requesting action from the title server.

  • Alert Events

    These events are fired in response to imposed limits being reached or to the occurrence of certain system errors.

The TraceView control allows users to filter most events according to their type. Some events, however, can not be filtered. MediaServer control events and their types are summarized in the following table:

Event | Type | Description
OnAdminBandwidthLimit | Admin | Fired when the aggregate bandwidth, as specified by the MaxBandWidth property, has been modified.
OnAdminClientLimit | Admin | Fired when an administration application changes the maximum number of clients.
OnAdminCServerOffline | Admin | Fired when an administration application takes a content server offline.
OnAdminDiskOffline | Admin | Fired when an administration application takes a disk offline.
OnAdminDiskOnline | Admin | Fired when an administration application takes a disk online.
OnAdminDiskRebuild | Admin | Fired when an administration application starts a disk rebuild process.
OnAdminDiskRebuildStop | Admin | Fired when an administration application stops a disk rebuild.
OnAdminFileBitRateLimit | Admin | Fired when the bandwidth of a title, as specified by the MaxTitleBitRate property, has been modified.
OnAdminKillClient | Admin | Fired when an administration application uses the Delete method in the Clients collection or when it calls the KillClient method.
OnAdminRestripeStart | Admin | Fired when an administration application starts title redeployment.
OnAdminRestripeStop | Admin | Fired when an administration application stops title deployment.
OnClientConnect | Client | Fired when a new client connection is established.
OnClientDisconnect | Client | Fired when a client disconnects from NetShow Theater.
OnClientPlay | Client | Fired when a client Player starts streaming a title.
OnClientStop | Client | Fired when a client Player stops streaming a title.
OnClientStride | Client | Fired when a client plays a title in fast-forward or fast-rewind mode.
OnConnectEvents | Unfiltered | Fired when a control in an administration application establishes a connection to the NetShow Monitor Service.
OnCServerFail | Alert | Fired when a content server has failed.
OnCServerLinkFail | Alert | Fired when a link between two content servers has failed.
OnCServerLinkUnfail | Server | Fired when a failed link between two content servers is restored.
OnCServerOffline | Server | Fired when a content server goes offline.
OnCServerOnline | Server | Fired when a content server goes online.
OnCServerStart | Server | Fired when a content server establishes a connection with the title server.
OnCServerUnknown | Alert | Fired when a content server has a duplicate or invalid ID.
OnDisconnect | Unfiltered | Fired when a control link to NetShow Theater is disconnected prematurely.
OnDisconnectEvents | Unfiltered | Fired when a control link in an administrative application loses connection to the NetShow Monitor Service.
OnDisconnectFunnel | Unfiltered | Fired when the data path from a computer adding content to a content server or streaming disconnects.
OnDiskFail | Alert | Fired when a disk in a content server fails to operate.
OnDiskOffline | Server | Fired when a content server's disk goes offline.
OnDiskOnline | Server | Fired when a content server's disk goes online.
OnDiskRebuildAbort | Server | Fired when a disk rebuild is aborted.
OnDiskRebuildFinish | Server | Fired when a disk rebuild is completed.
OnDiskRebuildProgress | Server | Fired periodically, on the order of a few seconds, to show the progress on the rebuilding of a content server disk.
OnDiskRebuildStart | Server | Fired when a disk rebuild is started.
OnMaxBandwidth | Alert | Fired when the maximum aggregate bandwidth surpasses the value specified by the MaxBandwidth property.
OnMaxClients | Alert | Fired when the number of clients connected surpasses the value specified by the MaxClients property.
OnReportError | Unfiltered | Fired when an error is reported.
OnRestripeAbort | Server | Fired when title redeployment is aborted.
OnRestripeFinish | Server | Fired when title redeployment is completed.
OnRestripeProgress | Server | Fired periodically, on the order of a few seconds, to show the title redeployment progress.
OnRestripeStart | Server | Fired when title redeployment is started.
OnServerFault | Alert | Fired when either fault tolerance is disabled and a single disk fails, or fault tolerance is enabled and more than one disk fails in the same mirror factor value.
OnServerOffline | Alert | Fired when a title server goes offline.
OnServerOnline | Server | Fired when a title server goes online.
OnTitleAddError | Unfiltered | Fired if an error occurs while a title is being added.
OnTitleCreate | Admin | Fired when a title starts to be added.
OnTitleRemove | Admin | Fired when a title has been successfully removed.
OnTitleRename | Admin | Fired when a title has been successfully renamed.
OnTitleUpdate | Admin | Fired when either a title's meta data is modified or when a title has been successfully added.


OnAdminBandwidthLimit Event

The MediaServer_OnAdminBandWidthLimit event is fired when the aggregate bandwidth (MaxBandwidth) has been modified.

Syntax

MediaServer_OnAdminBandWidthLimit( datetime, status, ipaddress, maxBandWidth, virtualPath )

Parameters

datetime

A Date value indicating the Greenwich Mean time (GMT) when the event occurred.

status

A Long value specifying the result passed back to the method that triggered this event.

ipaddress

A String value specifying the administrator's IP address.

maxBandWidth

A Long value specifying the new bit-rate limit in bits per second.

VirtualPath

A String value specifying the alias of the virtual root that caused the limit to be exceeded. A NULL value indicates a system-wide limit has been exceeded.

See Also

MaxBandwidth, MaxPhysicalBandwidth, MaxTitleBitRate, MinTitleBitRate


OnAdminClientLimit Event

The MediaServer_OnAdminClientLimit event is fired when the maximum number of allowable clients is changed.

Syntax

MediaServer_OnAdminClientLimit( datetime, status, IpAddress, count, virtualPath )

Parameters

datetime

A Date value indicating the GMT time when the event occurred.

status

A Long value specifying the result passed back to the method that triggered this event.

ipaddress

A String value specifying the administrator's IP address.

count

A Long value specifying the new client limit.

VirtualPath

A String value specifying the alias of the virtual root that caused the limit to be exceeded. A NULL value indicates a system-wide limit has been exceeded.


OnAdminCServerOffline Event

The MediaServer_OnAdminCServerOffline event is fired when an administration application takes a content server offline.

Syntax

MediaServer_OnAdminCServerOffLine( datetime, status, ipAddress, cserverid )

Parameters

datetime

A Date value specifying the GMT when the content server went offline.

status

A Long value specifying the result passed back to the method that triggered this event.

IpAddress

A String value specifying the IP address of the administrator.

cserverid

A Long value specifying the content server's ID. The value corresponds to the Id property of a content server object.

See Also

ContentServer.ID


OnAdminDiskOffline Event

The MediaServer_OnAdminDiskOffline event is fired when an administration application takes a disk offline.

Syntax

MediaServer_OnAdminDiskOffline( datetime, status, ipAddress, diskid )

Parameters

datetime

A Date value specifying the GMT when the disk went offline.

status

A Long value specifying the result passed back to the method that triggered this event.

ipAddress

A String value specifying the IP address of the administrator.

diskid

A Long value specifying the disk ID. The value corresponds to the Id property of a Disk object of the content server.

See Also

ContentServerDisk.ID


OnAdminDiskOnline Event

The MediaServer_OnAdminDiskOnline event is fired when an administration application takes a disk online.

Syntax

MediaServer_OnAdminDiskOnline( datetime, status, ipAdress, diskid )

Parameters

datetime

A Date value specifying the GMT when the disk went online.

status

A Long value specifying the result passed back to the method that triggered this event.

ipaddress

A String value specifying the IP Address of the administrator.

diskid

A Long value specifying the disk ID. The value can be retrieved from the Id property of a Disk object of the content server.

See Also

CServerDisk.ID


OnAdminDiskRebuild Event

The MediaServer_OnAdminDiskRebuild event is fired when a disk rebuild process is started.

Syntax

MediaServer_OnAdminDiskRebuild( datetime, status, ipaddress, diskid )

Parameters

datetime

A Date value specifying the GMT when the rebuild started.

status

A Long value specifying the result passed back to the method that triggered this event.

ipaddress

A String value specifying the IP address of the administrator.

diskid

A Long value specifying the content server disk ID. The value corresponds to the Id property of a Disk object of the content server.

See Also

OnDiskRebuildAbort, OnDiskRebuildFinish, OnDiskRebuildProgress, OnDiskRebuildStart, OnAdminDiskRebuildStop, ContentServerDisk.ID


OnAdminDiskRebuildStop Event

The MediaServer_OnAdminDiskRebuildStop event is fired when a disk rebuild process is stopped.

Syntax

MediaServer_OnAdminDiskRebuildStop( datetime, status, ipAddress, diskid )

Parameters

datetime

A Date value specifying the GMT when the rebuild stopped.

status

A Long value specifying the result passed back to the method that triggered this event.

ipaddress

A String value specifying the administrator's IP Address.

diskid

A Long value specifying the disk ID. The value corresponds to the Id property of a Disk object of the content server.

See Also

OnDiskRebuildAbort, OnDiskRebuildFinish, OnDiskRebuildProgress


OnAdminFileBitRateLimit Event

The MediaServer_OnAdminFileBitRateLimit event is fired when a title's bandwidth (MaxTitleBitRate) has been changed.

Syntax

MediaServer_OnAdminFileBitRateLimit(datetime, status, ipaddress, maxFileBitRate)

Parameters

datetime

A Date value specifying the GMT when the event was fired.

status

A Long value specifying the result passed back to the method that triggered this event.

ipaddress

A String value specifying the administrator's IP Address.

maxFileBitRate

A Long value specifying the maximum bandwidth in bits per second of a title. The value corresponds to that obtainable from the MaxTitleBitRate property.

Remarks

Reserved for future use.

See Also

MaxTitleBitRate


OnAdminKillClient Event

The MediaServer_OnAdminKillClient event is fired when an administration application uses the Delete method with the Clients collection, or when the application calls the KillClient method.

Syntax

MediaServer_OnAdminKillClient( datetime, status, ipaddress, clientid )

Parameters

datetime

A Date value specifying the GMT when the client was disconnected.

status

A Long value specifying the result passed back to the method that triggered this event.

ipaddress

A String value specifying the client's IP address.

clientid

A Long value specifying the ID of the disconnected client. The value corresponds to that obtainable from the Id property of a Client object.


OnAdminRestripeStart Event

The MediaServer_OnAdminRestripeStart event is fired when an administration application starts title redeployment.

Syntax

MediaServer_OnAdminRestripeStart( datetime, status, ipaddress )

Parameters

datetime

A Date value specifying the GMT when striping is started.

status

A Long value specifying the result passed back to the method that triggered this event.

ipaddress

A String value specifying the administrator's IP Address.

See Also

OnAdminRestripeStop, OnRestripeAbort, OnRestripeFinish, OnRestripeProgress, OnRestripeStart


OnAdminRestripeStop Event

The MediaServer_OnAdminRestripeStop event is fired when an administration application stops title redeployment.

Syntax

MediaServer_OnAdminRestripeStop( datetime, status, ipaddress )

Parameters

datetime

A Date value specifying the GMT when striping is stopped.

status

A Long value specifying the result passed back to the method that triggered this event.

ipaddress

A String value specifying the administrator's IP Address.

See Also

OnAdminRestripeStart, OnRestripeAbort, OnRestripeFinish, OnRestripeProgress, OnRestripeStart


OnClientConnect Event

The MediaServer_OnClientConnect event is fired when a new client connection is established.

Syntax

MediaServer_OnClientConnect( datetime, status, clientid, ipaddress, port )

Parameters

datetime

A Date value specifying the GMT when the client was connected.

status

A Long value specifying the result passed back to the method that triggered this event.

clientid

A Long value specifying the ID of the connected client. The value corresponds to that obtainable from the Id property of a Client object (implementing the IMSrvClient interface)

ipaddress

A String value specifying the client's IP address.

port

An Integer value specifying the client's TCP port.

Remarks

A server can have a limited number of client connections. Using the Administration control amounts to consuming one client connection.

See Also

OnClientDisconnect


OnClientDisconnect Event

The MediaServer_OnClientDisconnect event is fired when a client is disconnected from a NetShow Theater server.

Syntax

MediaServer_OnClientDisconnect( datetime, status, clientid, ipaddress, port )

Parameters

datetime

A Date value specifying the GMT when the client was disconnected.

status

A Long value specifying the result passed back to the method that triggered this event.

clientid

A Long value specifying the ID of the disconnected client. The value corresponds to that obtainable from the Id property of a Client object (implementing the IMSrvClient interface).

ipaddress

A String value specifying the client's IP address.

port

An Integer value specifying the client's TCP port.

See Also

OnClientConnect


OnClientPlay Event

The MediaServer_OnClientPlay event is fired when the user of a client player starts streaming a title.

Syntax

MediaServer_OnClientPlay( datetime, status, clientid, filename)

Parameters

datetime

A Date value specifying the GMT when the client player started streaming.

status

A Long value specifying the result passed back to the method that triggered this event.

clientid

A Long value specifying the client ID. The value corresponds to that obtainable from the Id property of a Client object (implementing the IMSrvClient interface).

filename

A String value specifying the title requested for playing by the client.

See Also

OnClientStop


OnClientStop Event

The MediaServer_OnClientStop event is fired when a client player stops streaming a title.

Syntax

MediaServer_OnClientStop( datetime, status, clientid, filename )

Parameters

datetime

A Date value specifying the GMT when the client player stopped streaming.

status

A Long value specifying the result passed back to the method that triggered this event.

clientid

A Long value specifying the client ID. The value corresponds to that obtainable from the Id property of a Client object (implementing the IMSrvClient interface.)

filename

A String value specifying the title the client was playing.

See Also

OnClientPlay


OnClientStride Event

The MediaServer_OnClientStride event is fired when a client player fast-forwards or rewinds a title.

Syntax

MediaServer_OnClientStride( datetime, status, clientid, filename )

Parameters

datetime

A Date value specifying the GMT time when fast-forward or rewind was activated.

status

A Long value specifying the result passed back to the method that triggered this event.

clientid

A Long value specifying the client ID. The value corresponds to that obtainable from the Id property of a Client object (implementing the IMSrvClient interface.)

filename

A String value specifying the title the client was playing.


OnConnectEvents Event

The MediaServer_OnConnectEvents event is fired when a control in an administration application connects to NetShow Monitor Service.

Syntax

MediaServer_OnConnectEvents( status )

Parameters

status

A Long value specifying the result passed back to the method that triggered this event.

See Also

OnDisconnectEvents


OnCServerFail Event

The MediaServer_OnCServerFail event is fired when a content server fails to operate.

Syntax

MediaServer_OnCServerFail( datetime, csrvId, status )

Parameters

datetime

A Date value specifying the GMT time when the content server failed.

csrvId

A Long value specifying the content server identifier. The value corresponds to that obtainable from the Id property of a ContentServer object (implementing the IMSrvCServer interface.)

status

A Long value specifying the result passed back to the method that triggered this event.


OnCServerLinkFail Event

The MediaServer_OnCServerLinkFail event is fired when a content server fails to link with the content server holding the next data block.

Syntax

MediaServer_OnCServerLinkFail( datetime, cserverid, peerCServerId, status )

Parameters

datetime

A Date value specifying the GMT time when the attempted link failed.

cserverid

A Long value specifying the ID of the content server that noted the broken link.

peerCServerId

A Long value specifying the ID of the subsequent content server that shares the broken link.

status

A Long value specifying the result passed back to the method that triggered this event.

See Also

OnCServerLinkUnFail


OnCServerLinkUnfail Event

The MediaServer_OnCServerLinkUnfail event is fired when a failed link between two content servers is restored.

Syntax

MediaServer_OnCServerLinkUnFail( datetime, cserverid, peercserverid, status)

Parameters

datetime

A Date value specifying the GMT time when the broken link was restored.

cserverid

A Long value specifying the ID of the content server that noted the broken link. The value corresponds to that obtainable from the Id property of a ContentServer object (implementing the IMSrvCServer interface).

peercserverid

A Long value specifying the ID of the subsequent content server that shared the broken link.

status

A Long value specifying the result passed back to the method that triggered this event.

See Also

OnCServerLinkFail


OnCServerOffline Event

The MediaServer_OnCServerOffline event is fired when a content server goes offline.

Syntax

MediaServer_OnCServerOffline( datetime, cserverid, status )

Parameters

datetime

A Date value specifying the GMT time when the content server went offline.

cserverid

A Long value specifying the content server ID. The value corresponds to that obtainable from the Id property of a ContentServer object (implementing the IMSrvCServer interface).

status

A Long value specifying the result passed back to the method that triggered this event.

See Also

OnCServerOnline


OnCServerOnline Event

The MediaServer_OnCServerOnline event is fired when a content server is online and ready to play titles.

Syntax

MediaServer_OnCServerOnline( datetime, cserverid, status )

Parameters

datetime

A Date value specifying the GMT time when the content server went online.

cserverid

A Long value specifying the ContentServer ID. The value corresponds to that obtainable from the Id property of a content server object (implementing the IMSrvCServer interface).

status

A Long value specifying the result passed back to the method that triggered this event.

See Also

OnCServerOffline


OnCServerStart Event

The MediaServer_OnCServerStart event is fired when a content server establishes a connection with the title server.

Syntax

MediaServer_OnCServerStart( datetime, cserverid, status )

Parameters

datetime

A Date value specifying the GMT time when the content server started.

cserverid

A Long value specifying the content server ID. The value corresponds to that obtainable from the Id property of a ContentServer object (implementing the IMSrvCServer interface).

status

A Long value specifying the result passed back to the method that triggered this event.


OnCServerUnknown Event

The MediaServer_OnCServerUnknown event is fired when a content server has a duplicate or invalid ID.

Syntax

MediaServer_OnCServerUnknown( datetime, ipaddress, status )

Parameters

datetime

A Date value specifying the GMT time when the event occurred.

ipaddress

A String value specifying the IP address of the content server in question.

status

A Long value specifying the result passed back to the method that triggered this event.

See Also

ServerStatus


OnDisconnect Event

The MediaServer_OnDisonnect event is fired when a client's connection to a NetShow Theater server is cut off asynchronously.

Syntax

MediaServer_OnDisconnect( status )

Parameters

status

A Long value specifying the result passed back to the method that triggered this event.

Remarks

This event occurs if an administration application uses the Delete method of a Clients collection object, or when the network link fails.


OnDisconnectEvents Event

The MediaServer_OnDisconnectEvents event is fired when a control in an administration application determines that it has been disconnected from the NetShow Monitor Service, or when the control is unable to connect to the service.

Syntax

MediaServer_OnDisconnectEvents( status )

Parameters

status

A Long value specifying the result passed back to the method that triggered this event.

See Also

OnConnectEvents


OnDisconnectFunnel Event

The MediaServer_OnDisconnnectFunnel event is fired when the data path from a computer adding content to a content server is interrupted.

Syntax

MediaServer_OnDisconnectFunnel( status )

Parameters

status

A Long value specifying the result passed back to the method that triggered this event.

Remarks

Due to network or other resource allocation problems, there is a chance that your funnel will be removed. However, the schedule is maintained.


OnDiskFail Event

The MediaServer_OnDiskFail event is fired when a disk in a content server fails to operate.

Syntax

MediaServer_OnDiskFail( datetime, diskid, status )

Parameters

datetime

A Date value specifying the GMT time when the disk operation failed.

diskid

A Long value specifying the disk ID. The value corresponds to that obtainable from the Id property of a Disk object (implementing the IMSrvCServerDisk interface).

status

A constant value, as defined in the MSRVDISKSTATUS enumeration, indicating the status of a content server disk.


OnDiskOffline Event

The MediaServer_OnDiskOffline event is fired when a content server's disk goes offline.

Syntax

MediaServer_OnDiskOffline( datetime, diskid, status)

Parameters

datetime

A Date value specifying the GMT time when the disk went offline.

diskid

A Long value specifying the disk ID. The value is specified by the Id property of a content server Disk object (of the IMSrvCServerDisk class).

status

A constant value, as defined in the MSRVDISKSTATUS enumeration, indicating the status of a content server disk.

See Also

OnDiskOnline


OnDiskOnline Event

The MediaServer_Online event is fired when a content server's disk goes online.

Syntax

MediaServer_OnDiskOnline( datetime, diskid, status )

Parameters

datetime

A Date value specifying is the GMT time when the disk went online.

diskid

A Long value specifying the disk ID.

status

A constant value, as defined in the MSRVDISKSTATUS enumeration, indicating the status of a content server disk.

See Also

OnDiskOffline


OnDiskRebuildAbort Event

The MediaServer_OnDiskRebuildAbort event is fired when a disk regeneration is stopped.

Syntax

MediaServer_OnDiskRebuildAbort( datetime, diskid, status )

Parameters

datetime

A Date value specifying the GMT time when the disk rebuild was aborted.

diskid

A Long value specifying the disk ID.

status

A constant value, as defined in the MSRVDISKSTATUS enumeration, indicating the status of a content server disk.

See Also

OnAdminDiskRebuild, OnDiskRebuildFinish, OnDiskRebuildProgress, OnDiskRebuildStart


OnDiskRebuildFinish Event

The MediaServer_OnDiskRebuildFinish event is fired when a disk regeneration is completed.

Syntax

MediaServer_OnDiskRebuildFinish( datetime, diskid, status )

Parameters

datetime

A Date value specifying the GMT time when the disk rebuild finished.

diskid

A Long value specifying the disk ID.

status

A constant value, as defined in the MSRVDISKSTATUS enumeration, indicating the status of a content server disk.

See Also

OnAdminDiskRebuild, OnDiskRebuildAbort, OnDiskRebuildProgress, OnDiskRebuildStart


OnDiskRebuildProgress Event

The MediaServer_OnRebuildProgress event is fired every 30 seconds to show the progress on the rebuilding of a content server disk.

Syntax

MediaServer_OnDiskRebuildProgress( datetime, diskid, bytesRebuilt, BytesTotal )

Parameters

datetime

A Date value specifying the GMT time when the progress notification event last occured.

diskID

A Long value specifying the disk ID. The value corresponds to the Id property of a content server Disk object.

BytesRebuilt

A Double value specifying number of bytes that have rebuilt.

BytesTotal

A Double value specifying total number of bytes to be rebuilt.

Remarks

Logging this event in TraceView could result in an excessive number of notifications of such events. It is recommended that you do not log this event.

See Also

OnAdminDiskRebuild, OnDiskRebuildAbort, OnDiskRebuildFinish, OnDiskRebuildStart


OnDiskRebuildStart Event

The MediaServer_OnDiskRebuildStart event is fired when a disk regeneration is started.

Syntax

MediaServer_OnDiskRebuildStart( datetime, diskID, status )

Parameters

datetime

A Date value specifying the GMT time when the rebuild started.

diskid

A Long value specifying the disk ID. The value corresponds to the Id property of a content server Disk object.

status

A constant value, as defined in the MSRVDISKSTATUS enumeration, indicating the status of a content server disk.

See Also

OnAdminDiskRebuild, OnDiskRebuildAbort, OnDiskRebuildFinish, OnDiskRebuildProgress


OnMaxBandwidth Event

The MediaServer_OnMaxBandwidth event is fired when a NetShow Theater server exceeds the maximum configured bandwidth.

Syntax

MediaServer_OnMaxBandwidth( datetime, rate, virtualPath )

Parameters

datetime

A Date value specifying the GMT time when the event occurred.

rate

A Double value specifying the current maximum aggregate bandwidth in bits per second.

VirtualPath

Reserved for future use.

Remarks

This event is called when the sum of all client bandwidth use exceeds the amount specified by the MaxBandwidth property. To receive notification of this event, the AlertEvents property must first be set to TRUE.

See Also

MaxBandwidth, MaxPhysicalBandwidth


OnMaxClients Event

The MediaServer_OnClients event is fired when a client connects to a NetShow Theater server, and it causes the maximum number of clients to be reached.

Syntax

MediaServer_OnMaxClients( datetime, count, virtualPath )

Parameters

datetime

A Date value specifying the GMT time when the maximum client limit was reached.

count

A Long value specifying maximum number of clients.

Virtualpath

Reserved for future use.

Remarks

This event is called when the total number of connected clients exceeds the amount specified by the MaxClients property. To receive notification of this event, the AlertEvents property must first be set to TRUE.


OnReportError Event

The MediaServer_OnReportError event is fired when an error is reported in the NetShow Theater system.

Syntax

MediaServer_OnReportError( status )

Parameters

status

A Long value specifying the result passed back to the method that triggered this event. Reserved for future use.


OnRestripeAbort Event

The MediaServer_OnRestripeAbort event is fired when title redeployment is aborted.

Syntax

MediaServer_OnRestripeAbort( datetime, reason )

Parameters

datetime

A Date value specifying the GMT time when striping was aborted.

reason

A Long value specifying the reason

See Also

OnAdminRestripeStart, OnAdminRestripeStop, OnRestripeFinish, OnRestripeProgress, OnRestripeStart


OnRestripeFinish Event

The MediaServer_OnRestripeFinish event is fired when title redeployment is completed.

Syntax

MediaServer_OnRestripeFinish( datetime, status )

Parameters

datetime

A Date value specifying the GMT time when striping was completed.

status

A Long value specifying the result passed back to the method that triggered this event.

See Also

OnAdminRestripeStart, OnAdminRestripeStop, OnRestripeAbort, OnRestripeProgress, OnRestripeStart


OnRestripeProgress Event

The MediaServer_OnRestripeProgress event is fired every 30 seconds to show the title redeployment progress.

Syntax

MediaServer_OnestripeProgress( datetime, percentage )

Parameters

datetime

A Date value specifying the GMT time when the event occurred.

percentage

A Long value specifying the percentage of restriping completed.

See Also

OnAdminRestripeStart, OnAdminRestripeStop, OnRestripeAbort, OnRestripeProgress, OnRestripeStart


OnRestripeStart Event

The MediaServer_OnRestripeStart event is fired when title redeployment is started.

Syntax

MediaServer_OnRestripeStart( datetime, status )

Parameters

datetime

A Date value specifying the GMT time when striping was started.

status

A Long value specifying the result passed back to the method that triggered this event.

See Also

OnAdminRestripeStart, OnAdminRestripeStop, OnRestripeAbort, OnRestripeFinish, OnRestripeProgress


OnServerFault Event

The MediaServer_OnServerFault event is fired when a title server is not performing optimally.

Syntax

MediaServer_OnServerFault( datetime, status )

Parameters

datetime

A Date value specifying the GMT time when the event occurred.

status

A Long value specifying the result passed back to the method that triggered this event.

Remarks

You can query the ServerStatus property to determine the condition of the server.


OnServerOffline Event

The MediaServer_OnServerOffline event is fired when a title server goes offline.

Syntax

MediaServer_OnServerOffline( datetime, status )

Parameters

datetime

A Date value specifying the GMT time when the title server went offline.

status

A Long value specifying the result passed back to the method that triggered this event.


OnServerOnline Event

The MediaServer_OnServerOnline event is fired when a title server goes online

Syntax

MediaServer_OnServerOnline( datetime)

Parameters

datetime

A Date value specifying the GMT time when the content server went online.


OnTitleAddError Event

The MediaServer_OnTitleAddError event is fired when an error occurs while a title is being added to NetShow Theater server on the current computer.

Syntax

MediaServer_OnTitleAddError( title, error, bstrError )

Parameters

title

A String value specifying the name of the title just added.

error

A Long value specifying the error code.

BstrError

A String value specifying the error message.

See Also

Add, AddTitle, OnTitleCreate


OnTitleCreate Event

The MediaServer_OnTitleCreate event is fired when a new title is added to a title server.

Syntax

MediaServer_OnTitleCreate( datetime, status, ipaddress, titlename )

Parameters

datetime

A Date value specifying the GMT time when the title was appended to the server.

status

A Long value specifying an HRESULT status such as NS_S_PENDING or E_ACCESSED_DENIED.

Ipaddress

A String value specifying the IP address of the title server.

titlename

A String value specifying the name of the added title.

See Also

Add, AddTitle


OnTitleRemove Event

The MediaServer_OnTitleRemove event is fired when a title has been successfully removed from a NetShow Theater Server.

Syntax

MediaServer_OnTitleRemove( datetime, reason, ipaddress, titlename )

Parameters

datetime

A Date value specifying the GMT time when the title was removed.

Reason

A Long value specifying an HRESULT result status.

Ipaddress

A String value specifying the IP address of the title server.

titlename

A String value specifying the title that was removed.

See Also

OnTitleRename, OnTitleUpdate


OnTitleRename Event

The MediaServer_OnTItleRename event is fired when a title on a NetShow Theater server has been successfully renamed.

Syntax

MediaServer_OnTitleRename(datetime, reason, ipaddress, sourcename, targetname)

Parameters

datetime

A Date value specifying the GMT time when the title was renamed.

Reason

A Long value specifying an HRESULT result status.

Ipaddress

A String value specifying the IP address of the title server.

sourcename

A String value specifying the original title name.

targetname

A String value specifying the title's new name.

See Also

OnTitleRemove, OnTitleUpdate


OnTitleUpdate Event

The MediaServer_OnTitleUpdate event is fired when a title’s metadata is modified.

Syntax

MediaServer_OnTitleUpdate( datetime, reason, ipaddress, titlename )

Parameters

datetime

A Date value specifying the GMT time when the title was modified.

reason

A Long value specifying an HRESULT result status.

ipaddress

A String value specifying the IP address of the title server.

titlename

A String value specifying the file name of the title.

See Also

OnTitleRemove, OnTitleRename


Objects Contained in the MediaServer Control

The MediaServer control maintains and uses the following objects to provide various types of services. Each object adopts and implements a COM interface, which is listed in the following table as well.

Object | Interface | Description
Client | IMSrvClient | Client object obtained from a Clients collection object.
Clients | IMSrvClients | A collection of clients obtained from the Clients method of a MediaServer object.
ContentServer | IMSrvCServer | ContentServer object obtained from a ContentServers collection object.
ContentServers | IMSrvCServers | A collection of content servers obtained from the Cservers method of a MediaServer object.
ContentServerDisk | IMSrvCServerDisk | A content server Disk object obtained from a content server Disks collection object.
ContentServerDisks | IMSrvCServerDisks | A collection of content server disks obtained from the Disks method of a ContentServer object.
Logging | IMSrvLogging | A Logging object that encapsulates the logging of the server configuration.
Title | IMSrvTitle | A Title object obtained from a Titles collection object.
Titles | IMSrvTitles | A collection of titles obtained from the Titles method of a MediaServer object.
Walker | IMSrvWalkerEntry | Walker object obtained from a Walkers collection.
Walkers | IMSrvWalkers | A collection of walkers obtained from the Walkers method of a MediaServer object.


Client Object

The MediaServer control manipulates NetShow Theater clients by means of Client objects that adopt and implement the IMSrvClient interface. The Client object merely encapsulates the properties of a client. It does not support any methods or events.


Client Properties

Property | Access | Description
ID | R | Returns a Long value specifying the NetShow Theater client identifier.
IPAddress | R | Returns a String value specifying the IP address of the client.
Status | R | Returns a Long value specifying the status of the client.
Subscriber | R | Returns a String value specifying the name of the host computer of the client.
TitleName | R | Returns a String value specifying the title that the client is viewing.


Client.ID Property

The Client.ID property returns a Long value specifying the ID of a client.

Syntax

Client.ID

Example

Sub enumClients(server As String)
    Dim client As IMSrvClient
    MediaServer1.SetServer server
    For Each client In MediaServer1.Clients
        MsgBox client.ID
    Next
End Sub

See Also

Client object, Content Server object, Content Server Disk object


Client.IPAddress Property

The Client.IPAddress property returns a String value specifying the clients IP address.

Syntax

Client.IPAddress


Client.Status Property

The Client.Status property returns a Long value specifying status information for a client.

Syntax

Client.Status

Return Values

The status for a client can be one of the following:

Client Status | Code
Inactive | 0
Active | 1
Striding | 2
NowPlaying | 3
Disconnecting | 4

Example

The following Visual Basic example outputs the status for each client in a client collection.

Sub enumClients(server As String)
    Dim client As IMSrvClient
    MediaServer1.SetServer server
    For Each client In MediaServer1.Clients
        MsgBox "Client " & Str$(client.ID) &
               "status: " & Str$(client.status)
    Next
End Sub

See Also

Client object, Content Server object, Content Server Disk object


Client.Subscriber Property

The Client.Subscriber property returns a String value specifying the name of the computer the client is running on.

Syntax

Client.Subscriber


Client.TitleName Property

The Client.TitleName property returns a String value specifying the title name that the client is viewing.

Syntax

Client.TitleName

Remarks

This property is valid only if the title is being played.


Clients Object

A Clients object is a collection object that manages a set of Client objects. It implements the IMSrvClients interface.


Clients Methods

Method | Description
Remove | Disconnects a client and removes the associated Client object from the Clients collection.


Clients.Remove Method

The Clients.Remove method removes a specific member from the Clients collection.

Syntax

Client.Remove(index)

Parameters

index

An integer specifying the index of a requested Client object in the Clients collection.

See Also

Clients object, Titles object


Clients Properties

Property | Access | Description
Count | R | Returns a Long value specifying the number of objects in the collection.
Item | R | Returns a given Client object.


Clients.Count Property

The Clients.Count property returns a Long value specifying the number of objects in a collection.

Syntax

Clients.Count

Example

The following example queries the count property to get the number of clients connected to the server (“MyServer”).

MediaServer1.SetServer ("MyServer")
Dim clients As IMSrvClients
clients = MediaServer1.Clients
MsgBox "There are " & clients.count & " clients."

See Also

Clients object, Content Servers object, Content Server Disks object, Titles object, Walkers object


Clients.Item Property

The Clients.Item property returns a specific member of a collection object either by position or by key.

Syntax

Clients.Item varitem

Parameters

varitem

A numeric or String expression that specifies the position of a member of the collection.

Remarks

There are two equivalent ways to retrieve a member object from a collection object, as shown in the following example:

DIM clients as IMSrvClients
clients = MedialServer1.Clients
if clients(0).ID <> clients.Item(0).ID Then
   MsgBox "Something is terribly wrong."
End if

See Also

Clients object, Content Servers object, Content Server Disks object, Titles object, Walkers object


ContentServer Object

The MediaServer control works with a NetShow Theater content server by manipulating a ContentServer object that implements the IMSrvCServer interface.


ContentServer Properties

Property | Access | Description
Disks | R | Returns a ContentServerDisks collection.
ID | R | Returns a Long value specifying the identifier of the content server.
Name | R | Returns a String value specifying the name of the host computer of the content server.
Status | R | Returns a Long value specifying the status of the content server. S_OK or zero means that the server is running normally.


ContentServer.Disks Property

The ContentServer.Disks property returns a Disks collection obtained from a ContentServer object.

Syntax

ContentServer.Disks


ContentServer.ID Property

The ContentServer.ID property returns a Long value specifying the ID for a content server.

Syntax

ContentServer.ID

Example

The following Visual Basic code writes out the name of each content server.

Sub enumCServers(server As String)
    Dim CServer As IMSrvCServer
    MediaServer1.SetServer server
    For Each CServer In MediaServer1.CServers
        MsgBox CServer.Name
    Next
End Sub

See Also

Client object, Content Server object, Content Server Disk object


ContentServer.Name Property

The ContentServer.Name property returns a String specifying the computer name of a content server.

Syntax

ContentServer.Name

See Also

ClientView object, Content Server Disk object, Content Server object, MediaServer object, ServerView object, Title object, TitleView object, TraceView object


ContentServer.Status Property

The ContentServer.Status property returns a Long value specifying status information for a content server.

Syntax

ContentServer.Status

Remarks

The return value is an HResult value.

See Also

Client object, Content Server object, Content Server Disk object


ContentServers Object

A ContentServers object is an instance of the IMSrvCServers interface and represents a collection of ContentServer objects. The MediaServer control accesses a ContentServers collection by invoking the CServers method.


ContentServers Properties

Property | Access | Description
Count | R | Returns a Long value specifying the number of objects in the collection.
Item | R | Returns a given ContentServer object from this collection object.


ContentServers.Count Property

The ContentServers.Count property returns a Long value specifying the number of objects in a ContentServers collection.

Syntax

ContentServers.Count

Remarks

You can use this property with a For...Next statement to carry out an operation on the objects in a collection, as shown in the following example.

Example

The following example uses the count property to enumerate through a ContentServers collection object to output the Ids of each ContentServer.

MediaServer1.SetServer ("MyServer")
Dim cservers As IMSrvCServers
Set cservers = MediaServer1.CServers
For i=0 To cserver.Count – 1
    MsgBox cservers(i).ID
Next i

See Also

Clients object, Content Servers object, Content Server Disks object, Titles object, Walkers object


ContentServers.Item Property

The ContentServers.Item property returns a specific member of a content server collection either by position or by key.

Syntax

ContentServers.Item(varitem)

Parameters

varitem

A numeric or string expression that specifies the position of a member of the collection.

See Also

Clients object, Content Servers object, Content Server Disks object, Titles object, Walkers object


ContentServerDisk Object

The MediaServer control accesses a content server disk by means of a ContentServerDisk object, which is an instance of an IMSrvServerDisk interface.


ContentServerDisk Methods

Method | Description
Online | Takes a content server disk online or offline.
Rebuild | Starts, pauses, or stops the rebuilding of a content server disk.


ContentServerDisk.Online Method

The ContentServerDisk.Online method takes a content server disk online or offline.

Syntax

ContentServerDisk.Online (boolval)

Parameters

boolval

A Boolean expression, True brings the disk online; False takes it offline.


ContentServerDisk.Rebuild Method

The ContentServerDisk.Rebuild method starts, pauses, or stops the rebuilding of a content server disk.

Syntax

ContentServerDisk.Rebuild (rebuildopt)

Parameters

rebuildopt

A rebuild option with one of the following values

Constant | Value
MSRVREBUILD_LAST | 0
MSRVREBUILD_STOP | 1
MSRVREBUILD_FROM_START | 2

See Also

Content Server Disk object, ServerView object


ContentServerDisk Properties

Property | Access | Description
ID | R | Returns a Long value specifying the disk identifier of a content server.
Name | R | Returns a String value specifying the drive letter of a content server disk.
Rebuilt | R | Returns a Double value specifying the number of bytes rebuilt when rebuilding is in process.
Size | R | Returns a Double value specifying the content server disk size in bytes.
Status | R | Returns the status of a content server disk.


ContentServerDisk.ID Property

The ContentServerDisk.ID property returns a Long value specifying the ID for a content server disk.

Syntax

ContentServerDisk.ID

Example

The following Visual Basic code outputs the name for each disk in a content server disk collection.

Sub enumDisks(server As String)
    Dim Disk As IMSrvCServerDisk
    Dim CServer As IMSrvCServer

    MediaServer1.SetServer server

    For Each CServer In MediaServer1.CServers
        For Each Disk In CServer.Disks
            MsgBox "Disk " & Disk.Name & " is on " & CServer.Name
        Next
    Next
End Sub

See Also

Client object, Content Server object, Content Server Disk object


ContentServerDisk.Name Property

The ContentServerDisk.Name property returns a String value specifying the drive letter of a content server disk.

Syntax

ContentServerDisk.Name

See Also

Content Server Disk object, Content Server object, MediaServer object, ServerView object


ContentServerDisk.Rebuilt Property

The ContentServerDisk.Rebuilt property returns a Double value specifying the number of bytes rebuilt if a rebuild process was started.

Syntax

ContentServerDisk.Rebuilt

Remarks

This property is valid only if the rebuilt bit is on.


ContentServerDisk.Size Property

The ContentServerDisk.Size property returns a Double value specifying a content server's disk size in bytes, or a Double value specifying a NetShow Theater title.

Syntax

ContentServerDisk.Size

See Also

Content Server Disk object, Title object


ContentServerDisk.Status Property

The ContentServerDisk.Status property returns a disk status code as defined in the MSRVDISKSTATUS enumeration.

Syntax

ContentServerDisk.Status

See Also

Content Server Disk object, Title object


ContentServerDisks Object

ContentServerDisks Collection Object

A ContentServerDisks collection object is an instance of the IMSrvContentDisks interface and represents a collection of ContentServerDisk objects. A ContentServer object invokes its Disks method to obtain this collection.


ContentServerDisks Properties

Property | Access | Description
Count | R | Returns a Long value specifying the number of objects in the collection.
Item | R | Returns a given Disk object from this collection.


ContentServerDisks.Count Property

The ContentServerDisks.Count property returns a Long value specifying the number of objects in a collection.

Syntax

ContentServerDisks.Count

Example

The following example uses the Count property to enumerate through a Clients collection object to output client IDs.

sub eumDisks(server As String)
    Dim Disk As IMSrvCServerDisk
    Dim CServer As IMSrvCServer

    MediaServer1.SetServer server
    For Each CServer In MediaServer1.CServers
        MsgBox "There are " & CServer.Disks.Count & " on " & CServer.Name
    Next
End Sub

See Also

Clients object, ContentServers object, ContentServerDisks object, Titles object, Walkers object


ContentServerDisks.Item Property

The ContentServerDisks.Item property returns a specific member of a collection object, either by position or by key.

Syntax

ContentServerDisks.Item(varitem)

Parameters

varitem

A numeric or string expression that specifies the position of a member of the collection.

See Also

Clients object, ContentServers object, ContentServerDisks object, Titles object, Walkers object


Title Object

A Title object is an instance of the IMSrvTitle interface and represents a NetShow Theater title.


Title Properties

Property | Access | Description
Attributes | R | Returns a Long value specifying an attribute of the title.
Author | RW | Returns or sets a String value specifying the author of the title.
BitRate | R | Returns a Long value specifying a bit rate, in bits per second, of the title.
Blocks | R | Returns a Long value specifying the number of blocks in the title.
Caption | RW | Returns or sets a String value specifying the caption of the title.
Copyright | RW | Returns or sets a String value specifying the copyright information.
CreationTime | R | Returns a Date value specifying the time when the title was added to NetShow Theater.
Description | RW | Returns or sets a String value specifying the description of the title.
Format | R | Returns a Long value specifying a format code of the title.
Name | RW | Returns or sets a String value specifying a name to identify the title.
PlayTime | R | Returns a Date value specifying the total playing time, in seconds, of the title.
Size | R | Returns a Double value specifying the size, in bytes, of the title.
Version | R | Returns a Long value specifying the format version of the title.


Title.Attributes Property

The Title.Attributes property returns a Long value specifying status information for a title.

Syntax

Title.Attributes

Return Values

The attributes can be one or more than one of the following values OR'ed together:

Disk Status | Bit Flag | Decimal Value
Allocated | 0x00080000 | 524288
Initialized | 0x00100000 | 1048576
Invalid | 0x00200000 | 2097152
Block Format | 0x00400000 | 4194304
Can Stride | 0x00800000 | 8388608
Can Seek | 0x01000000 | 16777216

Example

The following code evaluates each title in the collection for its initialized status. This example adds a title, without the VOD extension, to a list box (if it is initialized), or increments an uninitialized tally (if it isn’t).

Dim title As IMSrvTitle
Dim name As String
MediaServer1.SetServer ("MyServer")
INITIALIZED = 1048576
uninit = 0
For title In MediaServer1.Titles("*.vod")
   If (title.Attributes And INITIALIZED) Then
      name = title.Name
      lstServer.AddItem Left(name, Len(name)-4)
      Else
      uninit = uninit + 1
   End If
Next


Title.Author Property

The Title.Author property returns or sets a String of the title's author.

Syntax

Title.Author


Title.BitRate Property

The Title.BitRate property returns a Long value specifying the title's bit rate in bits per second.

Syntax

Title.BitRate

Example

The following Visual Basic code outputs the bit rate for each title in the collection.

MediaServer1.SetServer ("NYCServer8")
Dim title as IMSrvTitle
For Each title In MediaServer1.Titles("*.vod")
   MsgBox title.Name & “: “ & title.BitRate
Next

See Also

MaxBandwidth, MaxTitleBitRate, MinTitleBitRate


Title.Blocks Property

The Title.Blocks property returns a Long value specifying the number of blocks in a title.

Syntax

Title.Blocks


Title.Caption Property

The Title.Caption property returns or sets a String of the title caption.

Syntax

Title.Caption

Remarks

An example of this property is “Waiting for Guffman.” The Description property can contain any other identifying information and the Name property is used to identify the title on the server, such as “WaitGuff.vod.”

See Also

Name, Description


Title.Copyright Property

The Title.Copyright property returns or sets a String of the title copyright.

Syntax

Title.Copyright


Title.CreationTime Property

The Title.CreationTime property returns a Date value specifying the time the title was added to NetShow Theater.

Syntax

Title.CreationTime

Remarks

The Date value returned is expressed in coordinated universal time (UTC), which is a standard time format based on Greenwich Mean Time.

Example

The following Visual Basic code outputs the creation time for each title the collection.

Sub enumTitles(server As String)
    Dim title As IMSrvTitle

    MediaServer1.SetServer server

    For Each title In MediaServer1.Titles("*.vod")
        MsgBox title.Name & ":" & title.CreatTime
    Next
End Sub


Title.Description Property

The Title.Description property returns or sets a String of the title description.

Syntax

Title.Description


Title.Format Property

The Title.Format property returns a Long value specifying a title format code.

Syntax

Title.Format

Remarks

Reserved for future use.


Title.Name Property

The Title.Name property returns or sets a String of a name that identifies the title on the server, such as “Casablanca.vod.”

Syntax

Title.Name

See Also

Title object, TitleView object


Title.PlayTime Property

The Title.PlayTime property returns a Date value specifying a title's total playing time in seconds.

Syntax

Title.PlayTime


Title.Size Property

The Title.Size property returns a Double value specifying the size of a NetShow Theater title in bytes.

Syntax

Title.Size

Content Server Disk object, Title object


Title.Version Property

The Title.Version property returns a Long value specifying the version of a title.

Syntax

Title.Version


TitlesObject

Titles Collection Object

A Titles collection object implements the IMSrvTitles interface and is a collection of Title objects. A MediaServer object invokes its Titles method to obtain this collection.


Titles Methods

Method | Description
Add | Adds a title to a NetShow Theater server, and the corresponding Title object to this collection.
Remove | Removes a title from a NetShow Theater server, and the corresponding Title object from this collection.


Titles.Add Method

The Titles.Add method adds a title to the NetShow Theater server.

Syntax

Titles.Add( filename, titlename )

Parameters

filename

A String of the source video file name.

titlename

A String of the name to give to the added title.

Remarks

This method adds an object to the Titles collection object. This is an asynchronous operation.


Titles.Remove Method

The Titles.Remove method removes a specific title from a Titles collection on a NetShow Theater server.

Syntax

Titles.Remove

Parameters

index

An integer or string that uniquely identifies the object in the collection.

Remarks

You can not remove a title that is being added. Attempts to do so results in an E_Access_Denied error message. If you invoke the Titles.Remove method on a viewing title, the system generates a NS_S_Pending message. However, you will only get the S_OK message if you program with Visual Basic, which converts all success codes to S_OK.

See Also

Titles object


Titles Properties

Property | Access | Description
Count | R | Returns a Long value specifying the number of Title objects in this collection.
Item | R | Returns a given Title object from this collection.


Titles.Count Property

The Titles.Count property returns a Long value specifying the number of Title objects in a Titles collection object.

Syntax

Titles.Count

Remarks

You can use this property with a For...Next statement to carry out an operation on the objects in a collection, as shown in the example.

Example

The following example uses the count property to enumerate through a Titles collection to output the ID’s of Title member objects.

Sub enumTitles(server As String)
    Dim title As IMSrvTitle

    MediaServer1.SetServer server

    MsgBox "There are " & MediaServer1.Titles("*").Count & " titles."

    For Each title In MediaServer1.Titles("*")
        MsgBox title.Name
    Next
End Sub


Titles.Item Property

The Titles.Item property returns a specific member of a collection object either by position or by key.

Syntax

Titles.Item (varItem)

Parameters

varItem

A numeric or string expression that specifies the position of a member of the collection.


Walker Object

A Walker object is an instance of the IMSrvWalkerEntry interface.


Walker Properties

Property | Access | Description
ClsID | R | Returns a String value as the class identifier for instantiating a Walker object.
Extensions | R | Returns the file extensions that are specific to a Walker object.


Walker.ClsID Property

The Walker.ClsID property returns a String of the class identifier for instantiating a walker of a specific file type.

Syntax

Walker.ClsID


Walker.Extensions Property

The Walker.Extensions property returns the file extension that is specific to a Walker object.

Syntax

Walker.Extensions

Example

The following Visual Basic example outputs the type for each walker in a Walkers collection object.

Sub enumWalkers(server As String)
    Dim walker As IMSrvWalkerEntry

    ' NOTE: It is a known issue that you must be connected
    ' to a NetShow Theater Server in order to enumerate
    ‘ walkers on a users
    ' machine.

    MediaServer1.SetServer server

    For Each walker In MediaServer1.Walkers
        MsgBox walker.Extensions
    Next
End Sub


Walkers Collection Object

A Walkers collection object is an instance of IMSrvWalkers class and represents a collection of Walker objects. The MediaServer control calls its Walkers method to obtain a Walkers collection.


Walkers Object Methods

Method | Description
Find | Finds a Walker entry by matching its string specification for a format type.


Walkers.Find Method

The Walkers.Find method finds a WalkerEntry object by matching its string specification for a format type.

Syntax

Walkers.Find( strIndex, retval )

Parameters

strIndex

A String specification to match a Walker object type.

retval

Name to give the resulting Walker object.

Return Values

Returns an object of IMSrvWalker type.

Example

The following code finds a walker that can add a title of a certain extension to a NetShow Theater server and displays the class id of the walker if a suitable one can be found

Sub findWalker(server As String, extension As String)
    Dim walker As IMSrvWalkerEntry

    ' NOTE: It is a known issue that you must be connected
    ' to a server in order to find a walker on a users
    ' machine

    MediaServer1.SetServer server

    Set walker = MediaServer1.Walkers.Find(extension)

    If (Not walker Is Nothing) Then
        MsgBox walker.ClsId
    End If
End Sub


Walkers Properties

Property | Access | Description
Count | R | Returns a Long value specifying the number of Title objects in this collection.
Item | R | Returns a given Walker object from this collection.


Walkers.Count Property

The Walkers.Count property returns a Long value specifying the number of objects in a collection.

Syntax

Walkers.Count

Remarks


Walkers.Item Property

The Walkers.Item property returns a specific member of a collection object either by position or by key.

Syntax

Walkers.Item varItem

Parameters

varItem

A numeric or string expression that specifies the position of a member of the collection.


Logging Object

A logging object is an instance of the IMSrvLogging class.


Logging Methods

Method | Description
SetType | Sets the logic to be used on the server.


Logging.SetType Method

The Logging.SetType method sets the type of logging used to create files.

Syntax

Logging.SetType( logtype, size )

Parameters

logtype

The type of logging to be used. Valid types include:

Log Type | Description
BYSIZE | A new log is created when it reaches a specified size.
DAILY | A new log is created daily.
MONTHLY | A new log is created monthly.
WEEKLY | A new log is created weekly.

size

A Long of the new size.

See Also

Type


Logging Properties

Property | Access | Description
Directory | RW | Returns or sets a String value as the directory of the server log file.
Enabled | RW | Returns or sets a Boolean value to determine whether to enable logging or not.
Limit | R | Returns a Long value as the limit used to switch files on (based on type)
Type | R | Returns a type of logic used to switch files on.


Logging.Directory Property

The Logging.Directory property returns or sets a String of the directory into which the server will log.

Syntax

Logging.Directory( LogFileDir )

Parameters

LogFileDir

The directory in to which log files are saved to.

Example

The following code displays the current server-side logging directory (if it is enabled.)

Sub displayLoggingDirectory(server As String)
    Dim logging As IMSrvLogging

    MediaServer1.SetServer server

    Set logging = MediaServer1.logging

    If (logging.Enabled) Then
        MsgBox logging.Directory
    End If
End Sub


Logging.Enabled Property

The Logging.Enabled property returns or sets a Boolean value specifying whether or not logging is enabled.

Syntax

Logging.Enabled

Remarks

Valid values include thefollowing:

Value | Description
True | Indicates logging is enabled. This is the property's default value.
False | Indicates logging is disabled.

Example

The following code displays the current server-side logging directory (if it is enabled):

Sub displayLoggingDirectory(server As String)
    Dim logging As IMSrvLogging

    MediaServer1.SetServer server

    Set logging = MediaServer1.logging

    If (logging.Enabled) Then
        MsgBox logging.Directory
    End If
End Sub


Logging.Limit Property

The Logging.Limit property returns a Long value specifying the logging limit based on the type of logging used.

Syntax

Logging.Limit


Logging.Type Property

The Logging.Type property returns the type of logging used to create files.

Syntax

Logging.Type

Remarks

The log types are as follows:

Log Type | Description
BYSIZE | A new log is created when it reaches a specified size.
DAILY | A new log is created daily.
WEEKLY | A new log is created weekly.
MONTHLY | A new log is created monthly.

See Also

SetType


Programming Guide to the NetShow Theater View Controls

The NetShow Theater Administration View controls provide an easy-to-use interface for monitoring NetShow Theater Server activity. These controls have a graphical user interface and support built in features, such as drag-and-drop functionality, for end users. They also expose methods and properties and support events for programmatically manipulating the controls. The View controls include:

ServerView Control

The ServerView control is a tree view control managing one or more title servers, their content servers and content disks. Expanding each top node of the tree displays a clients icon, specifying the number of clients connected to the title server, and an icon for each content server managed by the title server. Expanding each content server node displays the disks managed by that content server.

ServerView also supports the following functions, which are accessed by right-clicking a selection in the control:

  • Connecting and disconnecting title servers.

  • Taking content disks on and off line, as well as rebuilding content disks and pausing their operation.

  • Accessing property sheets used to manage and configure titles, servers, clients, and logging.
ClientView Control

The ClientView control is a control that displays the title being played, the TCP/IP address, status, and ID number for each client connected to the server. ClientView supports the following functions, which are accessed by right clicking on a selected client:

  • Disconnecting the selected client.

  • Accessing a property sheet containing specific information about the selected client.
TitleView Control

The TitleView control is a control that displays information about each of the titles available on the server. Information displayed on the TitleView control includes name, size, creation date, length, author, copyright, and attributes associated with each title. Functions are accessed by right-clicking the control include:

  • Adding, deleting, and renaming titles.

  • Playing selected titles.

  • Selecting the fields to be displayed by the control.

  • Accessing a property sheet with additional information about the title.
TraceView Control

The TraceView control is a control that displays a list of events fired by the NetShow Theater server. TraceView displays the date and time the event was triggered and a description of the event. Functions are accessed by right-clicking the control include:

  • Pausing and resuming the trace.

  • Clearing all entries from the control.

  • Access to a property sheet that allows the user to select the type of events listed in the control. Events are categorized into the following types: Server, Client, Admin, and Alert.


Using the View Controls

This section of the SDK demonstrates how, in just a few simple steps, you can create administration and player applications by incorporating the ClientView, ServerView, TitleView, and TraceView controls.

The procedures in the Simple Administration Application work for Microsoft Visual Basic 5.0. However, the concepts can also be easily adapted for Web-based administration applications that uses HTML and script languages. The Simple Player Application illustrates the techniques used to embed a TitleView control and the Windows Media Player control in a Web page.


Simple Administration Application

This application uses all of the View controls on one form. It adds three Title Servers to the ServerView control named TitleServer1, TitleServer2, and TitleServer3. Information about the server currently selected in ServerView, is dynamically displayed in the TitleView, ClientView, and TraceView controls.

Form Layout

From the Visual Basic toolbox, place and size the ServerView, ClientView, TitleView and TraceView controls onto a form. Your form should look similar to the following:

Initializing the Controls

Add the following code to the Form_Load event to add the Title Servers to the ServerView control and set the other controls to display data about the first server in the list. Save the name of the first server in the list so you can check to see when it changes.

Dim strSelectedServer As String

Private Sub Form_Load()
 ' Add servers to ServerView tree
 ServerView1.AddServer ("TitleServer1")
 ServerView1.AddServer ("TitleServer2")
 ServerView1.AddServer ("TitleServer3")

 ' Save the default server name
 strSelectedServer = "TitleServer1"

 ' Set other view controls to default to 1st server
 ClientView1.SetServer (strSelectedServer)
 TitleView1.SetServer (strSelectedServer)
 TraceView1.SetServer (strSelectedServer)

End Sub
Selecting a New Server

Each time a new selection is made in the ServerView control, an OnSelectionChange event is triggered. This event can be used to change the data displayed in the other controls if a different server is selected. The following code uses the server name we saved in the FORM_LOAD procedure to determine if the server has changed.

Private Sub ServerView1_OnSelectionChanged(ByVal selection As Long, ByVal infotype As NSTAdminCtl.BaseInfoType)

Dim strNewServer As String ' New server selected
Dim objServer As Object ' Temp object

'
Set objServer = ServerView1.GetItemObject
strNewServer = objServer.Name

' If the server name has changed,
' set other view controls to new server.
If strNewServer <> strSelectedServer Then
   strSelectedServer = strNewServer
   ClientView1.SetServer (strSelectedServer)
   TitleView1.SetServer (strSelectedServer)
   TraceView1.SetServer (strSelectedServer)
End If

End Sub
Running the Application

Change the name values being passed in to the AddServer method to valid Title servers. If you connect successfully, your application should look something like this:

Tip: You can place each control on a tab of a tabbed dialog control, such as the Microsoft® Tabbed Dialog Control.


Simple Title Player Application

By combining the Media Player Control with the TitleView control, you can easily create an application that allows the user to select a title from the Title server and watch it with the player. This simple sample uses HTML and VBScript to demonstrate one solution for playing the current selection in the TitleView control with the Media Player control.

Connecting to the Title Server

Start the page … Add text box for the server and a button to initiate the set server method.

<HTML>
<HEAD> <TITLE>Simple Title View and Media Player Example</TITLE> </HEAD>
<BODY>
<CENTER>Title Server:
<INPUT TYPE="TEXT" NAME="SrvName" SIZE="25">
<INPUT TYPE="BUTTON" NAME="SetSrv" VALUE="Set Server">
<BR><BR>
Add the TitleView and MediaPlayer Controls

Use <OBJECT> tags to embed the controls in the page. Notice we added a param tag to indicate that the player should not begin playing the title when the file name is set.

<OBJECT ID="TitleView1" WIDTH=155 HEIGHT=240 CLASSID="CLSID:1E1BAAB1-3614-11D1-A5FE-00AA00BF93E3">
</OBJECT>

<OBJECT ID="MediaPlayer1" WIDTH=360 HEIGHT=240
  CLASSID="CLSID:22D6f312-B0F6-11D0-94AB-0080C74C7E95">
  <PARAM NAME="AutoStart" VALUE="FALSE">
</OBJECT>
Add Simple UI for the Player

Add the play and stop buttons to manipulate the Player control.

<BR><BR>
<INPUT TYPE="BUTTON" NAME="PlayBtn"  VALUE="    >     ">
<INPUT TYPE="BUTTON" NAME="StopBtn"   VALUE="    []    ">
<BR>
</CENTER>
</BODY>
Add the Subroutines to handle click events

The next step is to add four subroutines; three to process click events for the buttons we added to the page, and one to respond to the OnSelectionChanged event that is triggered when a title is selected from the TitleView control.

<SCRIPT LANGUAGE="VBScript">
<!--

' Connect to the specified Ttitle Server
Sub SetSrv_OnClick
  TitleView1.SetServer (SrvName.VALUE)
End Sub

' Set the file name based on title selected in TitleView
Sub TitleView1_OnSelectionChanged( selection )
  If selection <> 0 Then
     strNewTitle = TitleView1.CurrentSelectionName
     MediaPlayer1.FileName =  "nsm://" & SrvName.VALUE & "/" & strNewTitle
  End If
End Sub

' Play button click event.
' Make sure a title has been selected from TitleView
Sub PlayBtn_OnClick
  If  MediaPlayer1.FileName = "" Then
      MsgBox "Select a Title to Play"
  Else
     MediaPlayer1.Play
  End If
End Sub

' *** Stop button click event. ***
Sub StopBtn_OnClick
   MediaPlayer1.Stop
End Sub

-->
</SCRIPT>
</HTML>
Putting it All Together

The preceding HTML and VBScript code fragments can be pasted together to create a working Web page. Bring the page up in your browser and type in the name of a title server on your intranet. After successfully connecting to the server, the available titles should appear in TitleView control.


ClientView Control Reference

The ClientView control manages properties of a client computer connected to a Title server. It can be manipulated through it's methods, properties, and events.


ClientView Methods

Method | Description
Delete | Deletes the given client.
SetServer | Sets the server and event proxy.
ShowProperties | Shows the properties of an item returned by the OnSectionChanged event.


ClientView.Delete Method

The ClientView.Delete method disconnects a client from a NetShow Theater server or removes a title from a NetShow Theater server.

Syntax

ClientView.Delete (selection)

Parameters

selection

A Long value specifies the selection, obtained by CurrentSelection Property or the OnSelectionChanged Event.

See Also

ClientView object, TitleView object


ClientView.SetServer Method

The ClientView.SetServer method creates a connection to a NetShow Theater server and monitors the events from the proxy server.

Syntax

ClientView.SetServer( servername [, eventproxy] )

Parameters

servername

A String of the title server to connect to.

eventproxy

An optional String value specifying the name of the server where the NetShow Monitor Service is running

See Also

ClientView object, MediaServer object, TitleView object, TraceView object


ClientView.ShowProperties Method

The ClientView.ShowProperties method shows the properties for a selection.

Syntax

ClientView.ShowProperties(selection)

Parameters

selection

A Long value specifying the selection, obtained by CurrentSelection property or the OnSelectionChanged event.

Remarks

To show the properties for the current selection, specify –1 or NST_CURRENT_SELECTION. This method can show properties for a client, title, title server, content server, and content server disk in the View controls.

See Also

ClientView Object, ServerView Object, TitleView Object

ClientView object, ServerView object, TitleView object


ClientView Properties

Property | Access | Description
CurrentSelection | R | Returns the current selection.
CurrentSelectionID | R | Returns the currently selected client ID.
EventProxy | R | Returns the name of the event monitor.
Server | R | Returns the server object.


ClientView.CurrentSelection Property

The ClientView.CurrentSelection property returns a handle to the selected item.

Syntax

ClientView.CurrentSelection


ClientView.CurrentSelectionID Property

The ClientView.CurrentSelectionID property returns the ID of the selected item.

Syntax

ClientView.CurrentSelectionID


ClientView.EventProxy Property

The ClientView.EventProxy property returns the name of the server where the NetShow Monitor Services is running.

Syntax

ClientView.EventProxy


ClientView.Server Property

The ClientView.Server property returns the name of the title server.

Syntax

ClientView.Server


ClientView Events

Event | Description
OnSelectionChanged | Fired when the current selection changes.


ClientView.OnSelectionChanged Event

The ClientView.OnSelectionChanged event fires when the current selection changes.

Syntax

ClientView.OnSelectionChanged( selection, infoType )

Parameters

selection

A Long value specifying the newly selected item.

infoType

A value of BaseInfo type. These values are as follows:

InfoType | Constant | Value
No selection | NoSelection | 0
Title Server | ServerInfoType | 1
Clients | ClientsInfoType | 2
Content Server | ContentServerInfoType | 3
Content Server Disk | DiskInfoType | 4

Remarks

When there is no selection, the selection parameter has the value of 0 (zero) or NST_NO_SELECTION.

See Also

GetItemObject


ServerView Control Reference

The ServerView control provides tools for viewing one or more NetShow Theater servers. It can be manipulated using it's methods, properties, and events.


ServerView Methods

Method | Description
AddServer | Adds a server to the tree.
DiskOffLine | Takes a disk offline.
DiskOnLine | Takes a disk online.
GetItemObject | Returns a ServerView control object that contains information about the item.
PauseRebuild | Pauses the rebuild of a disk.
Rebuild | Rebuilds a disk.
RemoveServer | Disconnects a server and removes it from the tree.
ShowProperties | Shows the properties of a node.
ShowProperties | Shows the properties of a title server.


ServerView.AddServer Method

The ServerView.AddServer method adds a server to the tree, and optionally specifies the server for the NetShow Monitor Service.

Syntax

ServerView.AddServer( servername [, eventproxy ] )

Parameters

servername

A String value specifying the name of the NetShow Theater title server.

eventproxy

An optional String value specifying the name of the server where the NetShow Monitor Service is running.

Remarks

Specifying the server for the NetShow Monitor Service is not implemented in the current release.


ServerView.DiskOffLine Method

The ServerView.DiskOffLine method takes a content server disk offline.

Syntax

ServerView.DiskOffLine(selection)

Parameters

Selection

A Long value specifying the selection as obtained by the CurrentSelection property or the OnSelectionChanged event.

See Also

DiskOnLine


ServerView.DiskOnLine Method

The ServerView.DiskOnLine method brings a content server disk online.

Syntax

ServerView.DiskOnLine(selection)

Parameters

Selection

A Long value specifying the selection as obtained by the CurrentSelection property or the OnSelectionChanged event.

See Also

DiskOffLine


ServerView.GetItemObject Method

The ServerView.GetItemObject method returns a IMSrvServerViewObject object that contains information on the item.

Syntax

ServerView.GetItemObject([ selection ])

Parameters

Selection

A Long value specifying the selection as obtained by the CurrentSelection property or the OnSelectionChanged event.

See Also

OnSelectionChanged


ServerView.PauseRebuild Method

The ServerView.PauseRebuild method pauses the rebuild of a content server disk.

Syntax

ServerView.PauseRebuild( selection )

Parameters

selection

A Long value specifying the content server disk on which to pause rebuilding.

Remarks

To obtain the value of a particular selection, use the CurrentSelection property, or the OnSelectionChanged event. To invoke this method on the current selection, specify –1 or NST_CURRENT_SELECTION.


ServerView.Rebuild Method

The ServerView.Rebuild method starts the rebuilding of a content server disk.

Syntax

ServerView.Rebuild( Selection )

Parameters

Selection

A Long value specifying the content server disk to rebuild.

Remarks

To rebuild using the ServerView object, you can obtain the value of a particular selection by using the CurrentSelection property, or the OnSelectionChanged event. To invoke this method on the current selection, specify –1 or NST_CURRENT_SELECTION.

See Also

Content Server Disk object


ServerView.RemoveServer Method

The ServerView.RemoveServer method disconnects a server and removes its node from the tree.

Syntax

ServerView.RemoveServer( selection )

Parameters

selection

A Long value specifying the server to remove.

Remarks

To obtain the value of a particular selection, use the CurrentSelection property, or the OnSelectionChanged event. To invoke this method on the current selection, specify –1 or NST_CURRENT_SELECTION.

The selection parameter can be either a Long value or a String value of the server name.


ServerView.ShowProperties Method

The ServerView.ShowProperties method shows the properties for a selection.

Syntax

ServerView.ShowProperties( selection )

Parameters

selection

A Long value specifying the selection, obtained by the CurrentSelection property, or the OnSelectionChanged event.

Remarks

To obtain the value of a particular selection, use the CurrentSelection property, or the OnSelectionChanged event. To invoke this method on the current selection, specify –1 or NST_CURRENT_SELECTION.

See Also

ClientView object, TitleView object


ServerView.ShowServerProperties Method

The ServerView.ShowServerProperties method displays the properties of a NetShow Theater server.

Syntax

ServerView.ShowServerProperties( page )

Parameters

page

One of the four pages of the Properties dialog box as described in Remarks.

Remarks

This method requires specifying one of the following property pages.

Page | Description
ServerViewClientsPage | Clients properties dialog
ServerViewGeneralPage | General properties dialog
ServerViewLoggingPage | Logging properties dialog
ServerViewTitlesPage | Titles properties dialog


ServerView Properties

Property | Access | Description
CurrentSelection | RW | Returns or sets the current selection
DiskStatus | R | Retrieves the status of a disk.


ServerView.CurrentSelection Property

The ServerView.CurrentSelection property returns or sets a Vairant that can be either the index or the name of the currently selected item.

Syntax

ServerView.CurrentSelection


ServerView.DiskStatus Property

The ServerView.DiskStatus property returns a MSRVDISKSTATUS constant specifying the status of a content server disk.

Syntax

ServerView.DiskStatus(selection)

Parameter

Selection

A Long value specifying the index of the selected disk.


ServerView Events

Event | Description
OnDiskStatusChange | Triggered when the status of a content server disk changes.
OnSelectionChanged | Triggered when selection in the server view changes.
OnServerAdded | Fired when a server is added.
OnServerRemoved | Fired when a server is removed.


ServerView.OnDiskStatusChange Event

The ServerView.OnDiskStatusChange event is fired when the status of a content server disk changes.

Syntax

ServerView_OnDiskStatusChange( selection, status )

Parameters

selection

A Long value specifying the current selection in ServerView.

status

A MSRVDISKSTATUS specifying the status of the content server disk.

See Also

ServerStatus


ServerView.OnSelectionChanged Event

The ServerView.OnSelectionChanged event is fired when the current selection changes.

Object_OnSelectionChanged( selection, infoType )

Parameters

selection

A Long value specifying the newly selected item

infoType

A value of BaseInfo type. These values are as follows:

InfoType | Constant | Value
No selection | NoSelection | 0
Title Server | ServerInfoType | 1
Clients | ClientsInfoType | 2
Content Server | ContentServerInfoType | 3
Content Server Disk | DiskInfoType | 4

Remarks

When you expand a server in server view, you see its clients and the hierarchy of its content servers and content server disks.

To obtain NetShow Theater IDs for a selected Content Server or Content Server Disk, or the name of the title server, use the ServerView object GetItemObject method.

See Also

GetItemObject


ServerView.OnServerAdded Event

The ServerView.OnServerAdded event fires when a server is added.

Syntax

ServerView_OnServerAdded( selection )

Parameters

selection

A Long value specifying newly added server.


ServerView.OnServerRemoved Event

The ServerView.OnServerRemoved event is fired when a server is removed.

Syntax

ServerView_OnServerRemoved( server )

Parameters

server

A String specifying when the server name was removed.


TitleView Control Reference

The TitleView control contains events, methods, and properties for viewing the following title information.


TitleView Methods

Method | Description
AddTitle | Invokes a dialog for adding titles.
Delete | Deletes a given title from the title server.
Rename | Invokes a method for renaming a title.
SetServer | Sets the server and event proxy.
ShowProperties | Shows the properties of a given title.


TitleView.AddTitle Method

The TitleView.AddTitle method displays a dialog box for adding titles.

Syntax

TitleView.AddTitle

Parameters

This method has no parameters.


TitleView.Delete Method

The TitleView.Delete method removes a title from a NetShow Theater title server.

Syntax

TitleView.Delete(selection)

Parameters

selection

A Long value specifying the selection, obtained by CurrentSelection property, or the OnSelectionChanged event.

Remarks

To delete the current selection, specify –1 or NST_CURRENT_SELECTION as the selection.


TitleView.Rename Method

The TitleView.Rename method renames a title.

Syntax

TitleView.Rename( selection, newtitlename)

Parameters

selection

This parameter is a Long value specifying the index of the title to rename.

newtitlename

This parameter is a String containing the new title name.

Remarks

To obtain the value of a particular selection, use the CurrentSelection property, or the selection parameter of the OnSelectionChanged event. To invoke this method on the current selection, specify -1

To display a dialog box for renaming a title, specify an empty string for the newtitlename parameter, as shown in the following example:

TitleView1.Rename -1, ""

See Also

OnTitleRename


TitleView.SetServer Method

The TitleView.SetServer method connects to a NetShow Theater server.

Syntax

TitleView.SetServer( servername [, eventproxy ])

Parameters

servername

This parameter is a String value indicating the name of the title server to connect to.

eventproxy

An optional String value specifying the name of the server where the NetShow Monitor Service is running


TitleView.ShowProperties Method

The TitleView.ShowProperties method shows the properties for a selection.

Syntax

TitleView.ShowProperties( selection )

Parameters

selection

A Long value specifying the index of the selected title. This value can be obtained from the CurrentSelection property, or the selection parameter of the OnSelectionChanged Event.

Remarks

To show the properties for the current selection, specify –1 or NST_CURRENT_SELECTION. This method can show properties for a client, title, title server, content server, and content server disk in the View control.


TitleView Properties

Property | Access | Description
CurrentSelection | R | Returns the current selection.
CurrentSelectionName | R | Returns the current selection name.
EventProxy | R | Returns the event proxy.
Server | R | Returns the name of the title server.


TitleView.CurrentSelection Property

The TitleView.CurrentSelection property returns a handle to the selected item.

Syntax

TitleView.CurrentSelection

See Also

ClientView object, ServerView object, TitleView object


TitleView.CurrentSelectionName Property

The TitleView.CurrentSelectionName property returns a String value containing the name of the title selected in the TitleView control.

Syntax

TitleView.CurrentSelectionName

See Also

ClientView object, ServerView object


TitleView.EventProxy Property

The TitleView.EventProxy property returns the name of the server where the NetShow Monitor Service is running.

Syntax

TitleView.EventProxy

See Also

ClientView object, ServerView object


TitleView.Server Property

The TitleView.Server property returns the name of the title server.

Syntax

TitleView.Server

See Also

ClientView object, ServerView object


TitleView Events

Event | Description
OnSelectionChanged | Fired when the current selection has changed.


TitleView.OnSelectionChanged Event

The TitleView.OnSelectionChanged event is fired when the current selection changes.

Syntax

TitleView.OnSelectionChanged( selection )

Parameters

selection

A Long value specifying the index of the newly selected item. This parameter is zero (0) if no title is currently selected.

See Also

ServerView.GetItemObject, ClientView object, ServerView object, TitleView object


TraceView Control Reference

The TraceView control provides events, methods, and properties for monitoring NetShow Theater events.


TraceView.SetServer Method

The TraceView.SetServer method connects to a NetShow Theater title server.

Syntax

TraceView.SetServer( servername [, eventproxy])

Parameters

servername

A String value indicating the title server to connect to.

eventproxy

An optional String value specifying the name of the server where the NetShow Monitor Service is running. Reserved for future use.


TraceView.OnTraceStateChange Event

The TraceView.OnTraceStateChange event is triggered when user clears, resumes, or pauses a trace.

Syntax

TraceView.OnTraceStateChange( newstate )

Parameters

newstate

This parameter indicates the new state of trace. Possible values for this parameter include the following:

Value | State
0 | Active
1 | Paused


Global Data Types and Structures

The NetShow Theater Server Administration SDK defines a few enumerations and structures for data processing.


MSRVDISKSTATUS Structure

MSRVDISKSTATUS

The MSRVDISKSTATUS enumeration defines a set of enumerated constants that describe the status of a content server disk.

Status | Contant
MSRVDISK_NOERROR | 0
MSRVDISK_ONLINE | 0
MSRVDISK_CANT_OPEN | 1
MSRVDISK_INVALID_FORMAT | 2
MSRVDISK_IO_ERROR | 3
MSRVDISK_TIMEOUT | 4
MSRVDISK_INVALID_CONTENT_DRIVE | 5
MSRVDISK_UNINITIALIZED_DRIVE | 6
MSRVDISK_REBUILDING | 7
MSRVDISK_PARTIALLY_REBUILT | 8
MSRVDISK_CONTENT_SERVER_OFFLINE | 9
MSRVDISK_ADMIN_OFFLINE | 10
MSRVDISK_LOG_REPLAYING | 11
MSRVDISK_PENDING_ONLINE | 12
MSRVDISK_REMIRRORED | 13


MSRVSTATUS Structure

MSRVSTATUS

A server status can be one of the following values.

Constant | Value | Description
ONLINE | 0 | The title server is online and functioning normally.
FAULTED | 1 | The title server has a fault condition.
RESTRIPE | 2 | Redeployment of titles is in progress.


Microsoft® Media Player Control

[This is preliminary documentation and subject to change.]

The Microsoft® Media Player control (contained in Msdxm.ocx) is a Microsoft ActiveX® control used for adding multimedia playback capabilities to OLE-enabled documents and applications, as well as Web pages. It provides a programming interface for rendering a variety of network streaming and non-streaming multimedia formats. The Player control incorporates many of the features of the ActiveMovie control and the NetShow version 2.0 Player control, as well as many new features.

This SDK describes the rich set of functionality exposed by the Player control. It is divided into the following sections:

Section | Description
About the Player Control | This section describes the architecture of the control and its underlying technology.
Using the Player Control | This section is a guide to using and programming the control.
Player Control Reference | This section provides a reference of each method, property, and event exposed by the control.
Player Control Samples | This section provides sample code illustrating use of the Player control.

In addition to the components listed above, this SDK also describes the Media Player Netscape Plug-in.

General Notes

For general information about ActiveX controls, see the Microsoft ActiveX SDK.

For more information about using VBScript with ActiveX controls, see the Visual Basic Script home page.


About the Player Control

The Media Player control exposes methods and properties for manipulating multimedia playback from a Web page or application. Functionality exposed by the methods and properties includes:

  • Building custom user interfaces on top of the control. Buttons, boxes, and menus can be incorporated into your Web page or application for administering the control.
  • Performing VCR-like functions such as start, stop, pause, fast forward, rewind, mute, and volume adjustment.
  • Monitoring stream and station performance.
  • Retrieving information about the content, such as title, author, and copyright date.

Your application or Web page can also be designed to respond to event messages fired by the control. Events that trigger the control to fire an event include:

  • Warnings and errors encountered by the control.
  • Changes in the state of the stream changes, such as from a play state to a paused state.
  • Keyboard and mouse input.
  • The control disconnecting from a stream server.
  • Script commands being received by the control.

The Media Player is also provided as a standalone Player application based on the same technology as the Player control. However, the control allows you to create a user interface unique to your content, process any type of script commands, and integrate multimedia presentations into larger Web applications.


Media Player Control Architecture

The Media Player control is built on Microsoft DirectShow™ technology. DirectShow is a component object model (COM) based architecture that employs pluggable components called filters to process multimedia data. Each filter is designed to receive digital input, process the data, and pass the results on to the next filter. The filters are arranged in a configuration called a filter graph.

DirectShow technology is based on several Microsoft services, including:

  • Microsoft DirectDraw® for two dimensional graphics hardware acceleration.
  • Microsoft DirectSound® for audio mixing and low-latency audio.
  • Microsoft Direct3D® for three dimensional graphics hardware acceleration.

Filters and filter graphs can be created by implementing COM interfaces that use the class libraries and documentation provided by the DirectShow SDK. However, it is not necessary to understand Microsoft Visual C++® programming or COM to use the Player control.

The following diagram illustrates the relationship between DirectShow and the Media Player control.


Control Compatibility Modes

The Media Player control is designed to be a universal player for all types of multimedia data. It works equally well rendering NetShow's streaming media types and Active Movie's local playback media types. The Media Player control incorporates many of the attributes supported by the NetShow version 2.0 Player and ActiveMovie controls, along with new methods, properties, and events. In addition, the Media Player control can operate in one of the following three modes to provide compatibility with the NetShow version 2.0 Player and ActiveMovie controls:

  • MediaPlayer Mode: In this mode, the control supports all of the methods, properties, and event notifications documented in this SDK.
  • 43NSPlay Mode: In this mode, the control exposes the methods, properties, and events supported for the NetShow version 2.0 Player control.
  • ActiveMovie Mode: In this mode, the control exposes the methods, properties, and events supported for the Active Movie control.

All three modes provide the enhanced streaming and playback capabilities of the Media Player; however, each mode supports its own set of attributes.

The class ID used to instantiate the control determines the mode of operation. Using the class IDs previously reserved for the NetShow Player control or the ActiveMovie control will instantiate the MediaPlayer control in that alternate mode. This means that applications and Web pages created with the NetShow Player or ActiveMovie controls can utilize the improved performance of the MediaPlayer control with little or no changes to their code. In many cases, a Web page can be updated by simply changing the Codebase attribute to specify the .cab file containing the MediaPlayer control.

Installing the NetShow Player control or ActiveMovie control on your development platform after installing the MediaPlayer control will cause unexpected results.

Forward Compatibility

In addition to the attributes supported when the control is instantiated in NSPlay or ActiveMovie mode, a new property named MediaPlayer is exposed. This property provides access to the methods and properties supported in MediaPlayer mode. The following syntax is used to access MediaPlayer attributes when the control is operating in NSPlay or ActiveMovie mode:

AlternateMode.MediaPlayer.Atribute

Where AlternateMode is the player control object ID instantiated using the NSPlay or ActiveMovie class ID, and Attribute is any method or property exposed by the control in MediaPlayer mode. For example, to access the Volume property from code written for existing the NetShow version 2.0 Player control, use the following:

NSPlay1.MediaPlayer.Volume

Backward Compatibility

In addition to forward compatibility, the control also provides access to NetShow version 2.0 Player and ActiveMovie attributes in MediaPlayer mode. Two properties, NSPlay and ActiveMovie, are exposed when the control is instantiated normally. The following syntax is used to access NetShow Player or ActiveMovie properties and methods when the control is operating in MediaPlayer mode:

NormalMode.NSPlay.Attribute

Or

NormalMode.ActiveMovie.Attribute

Where NormalMode is the player control instantiated with the Media Player class ID and Attribute is any method or property exposed by the control in an alternate mode. For example, to access the Author property of the NetShow version 2.0 Player control from code written for the Media Player control, use the following:

MediaPlayer1.NSPlay.Author

Compatibility Considerations

Operating in forward and backward compatibility modes have the following restrictions:

  • The control only fires events that are supported for the mode in which the control is instantiated.
  • Many methods and properties exposed by the Media Player control have the same name as properties and methods exposed by the NetShow version 2.0 and ActiveMovie controls. Most of these attributes exhibit the functionality of their predecessors. However, methods with the same name and different behavior always function in the mode in which they are instantiated.
  • Mode switching is only allowed on properties accessed at run-time. You can not set properties for alternate modes at design time.

Control Class IDs

Following is a list of the class IDs used to instantiate the control in each mode:

Control Mode | Class ID
Media Player | 22d6f312-b0f6-11d0-94ab-0080c74c7e95
NSPlay | 2179C5D3-EBFF-11cf-B6FD-00AA00B4E220
ActiveMovie | 05589FA1-C356-11CE-BF01-00AA0055595A


Content Formats

The Media Player control acts as a universal player for rendering most of today's standard multimedia formats. This includes stored and live content in network streaming formats, as well as non-streaming formats. Network streaming formats supported by the player include:

  • Advanced Streaming Format (ASF).
  • Video On Demand (VOD).
  • Motion Picture Experts Group standard one, two, and three (MPEG-1, MPEG-2, and MPEG-3)

In addition to the standard formats listed above, the player supports playback of RealAudio (RA) and RealVideo (RV) content as well.

Non-streaming (local playback) formats supported by the control include all of the network streaming formats previously listed and the following:

  • Audio-Video Interleaved (AVI)
  • Quicktime (MOV)
  • Musical Instrument Digital Interface (MIDI)
  • Indeo 5
  • Waveform Audio (WAV)
  • Sound File (SND)
  • UNIX audio (AU)


Codecs

The Media Player control supports all of the major multimedia compression/decompression algorithms (codecs) in use today. The Player control automatically detects which codec is needed to decompress incoming data. Because the Media Player is based on DirectShow's extensible filter-based architecture, it is easy to add support for new codecs as they are created. The Media Player control also supports non-filter-based codecs, such as Audio Compression Manager (ACM) and Video Compression Manager (VCM). For a complete list of supported codecs, see the NetShow Web site (http://www.microsoft.com/netshow).

Since the decompression takes place on the client computer, some codecs must reside on the client. In most cases, the Media Player control .ocx file is packaged with the appropriate codecs into a .cab (cabinet) file before it is distributed to clients. Other codecs can be downloaded and installed after the player is installed.


Using the Media Player Control

This section of the SDK is divided into three parts.

  • Using the Control in a Web page
  • Using the Control in a Visual Basic Application
  • Control Features


Using the Control in a Web Page

Being an ActiveX control, the Media Player control makes use of Automation to expose methods and properties and provide event support. While ActiveX controls, like the Player control, can be used as components in a wide variety of programming environments, they are extremely well-suited for use in Web pages. ActiveX controls can be used to add exciting dynamic content to previously static Web pages, and they are easy to distribute over networks.

By using a scripting language such as VBScript or JScript, it is easy to embed the Media Player control in an HTML Web page. This section explains how to embed the Media Player control into an HTML page and use VBScript routines to manipulate it.

Inserting the Player Control

The <OBJECT> tag is used to embed ActiveX objects like the Media Player control into an HTML page. Following is an example of using the <OBJECT> tag to insert the Player control.

<OBJECT ID="MediaPlayer1" WIDTH=320 HEIGHT=240
 CLASSID="CLSID:22D6f312-B0F6-11D0-94AB-0080C74C7E95">
 CODEBASE="http://www.microsoft.com/netshow/download/en/nsasfinf.cab
#Version=5,1,51,115">
</OBJECT>

The following <OBJECT> tag attributes are required:

  • ID - The name used to reference this instance of the control.
  • CLSID - The Global Class Identifier (CLSID) of the Media Player control.
  • HEIGHT and WIDTH - The height and width of the control in pixels. These attributes are required; however, in most cases their values are ignored by the control.

Using the CODEBASE attribute is strongly recommended. It contains a URL pointing to where the Player control can be found if it is unavailable on a user's system. Besides the address of the player object, the CODEBASE attribute may also optionally specify a version number of the control.

The Player control is available on Microsoft's Web site packaged as a .cab (cabinet) file. The .ocx file containing the control, along with the codecs needed to support the control, are compressed into the cabinet. An .inf file included in the cabinet specifies the files that need to be downloaded, and performs the setup for the control to run.

Setting Control Properties with the Param Tag

One option for setting the properties of a control in a Web page is adding <Param> tags between the <Object> and </Object> tags. This is an ideal method for setting design time properties. Following is an example of the previous <Object> tag with some <Param> tags added:

<OBJECT ID="MediaPlayer1" WIDTH=320 HEIGHT=240
 CLASSID="CLSID:22D6f312-B0F6-11D0-94AB-0080C74C7E95">
 CODEBASE="http://www.microsoft.com/netshow/download/en/nsasfinf.cab
#Version=5,1,51,115">
 <Param Name="FileName" Value="C:\ASFRoot\Welcome.asf">
 <Param Name="ShowControls" Value="False">
 <Param Name="AutoRewind" Value="True">
 <Param Name="AutoStart" Value="False">
</OBJECT>

The <Param> tags used in our example have two fields; the first is the name of the property being set, and the second specifies the value the property is set to. In the example above, the first <Param> tag sets the FileName property to C:\ASFRoot\Welcome.asf. The remaining <Param> tags change the default values of the AutoRewind property to TRUE and the ShowControls and AutoStart and properties to FALSE.

Adding a Simple User Interface for the Control

Adding a few buttons is the simplest way to demonstrate Player control operation. Add the following three button controls to the body of your HTML page: one to start the Player control, one to stop it, and one to display the current version of the Player control.

<INPUT TYPE="BUTTON" NAME="BtnPlay" VALUE="Play">
<INPUT TYPE="BUTTON" NAME="BtnStop" VALUE="Stop">
<INPUT TYPE="BUTTON" NAME="BtnAbout" VALUE="About">

Adding the Scripting Code

Scripting code adds interactivity to your page, allowing you to programmatically respond to events, call methods, and change run-time properties. First, you must notify the browser which scripting language you intend to use with a <SCRIPT> tag. Include the script commands within a comment so browsers that do not support scripting will not interpret your code as text and display it on the page.

For this sample, VBScript is used. Put the <SCRIPT> tag anywhere in the BODY and embed the comment-surrounded code within the <SCRIPT> and </SCRIPT> tags. The following code calls the Player control methods in response to events triggered by clicking the button controls.

<SCRIPT LANGUAGE="VBScript">
<!--
Sub BtnAbout_OnClick
   MediaPlayer1.AboutBox()
End Sub
Sub BtnPlay_OnClick
    MediaPlayer1.Play
End Sub
Sub BtnStop_OnClick
    MediaPlayer1.Stop
    MediaPlayer1.CurrentPosition = 0
End Sub
-->
</SCRIPT>

Each subroutine is attached to a specific button that was defined in the FORM section. When an event is triggered by a button being clicked, the code makes a call (or series of calls) to the Player control.

Simple Player Control Web Page

Combining the elements discussed previously in this section and adding them to a Web page, you can see how the pieces fit together.

<HTML>
<HEAD><TITLE>Media Player Test</TITLE></HEAD>
<BODY>
<OBJECT ID="MediaPlayer1" WIDTH=320 HEIGHT=240
 CLASSID="CLSID:22D6f312-B0F6-11D0-94AB-0080C74C7E95">
 CODEBASE="http://www.microsoft.com/netshow/download/en/nsasfinf.cab
#Version=5,1,51,115">
 <Param Name="FileName" Value="C:\ASFRoot\Welcome.asf">
 <Param Name="ShowControls" Value="False">
 <Param Name="AutoRewind" Value="True">
 <Param Name="AutoStart" Value="False">
</OBJECT>
<BR>
<INPUT TYPE="BUTTON" NAME="BtnPlay" VALUE="Play">
<INPUT TYPE="BUTTON" NAME="BtnStop" VALUE="Stop">
<INPUT TYPE="BUTTON" NAME="BtnAbout" VALUE="About">
<SCRIPT LANGUAGE="VBScript">
<!--
Sub BtnAbout_OnClick
   MediaPlayer1.AboutBox
End Sub
Sub BtnPlay_OnClick
    MediaPlayer1.Play
End Sub
Sub BtnStop_OnClick
    MediaPlayer1.Stop
    MediaPlayer1.CurrentPosition = 0
End Sub
-->
</SCRIPT>
</BODY>
</HTML>

Try this code with a multimedia file on your computer. Copy and paste this code into a text file and change the FileName <Param> tag to specify the relative path and protocol of the file you wish to play.


Using the Player Control in a Visual Basic Application

ActiveX technology is an ideal way to add multimedia to a Web page. However, under certain circumstances a standalone application may be more appropriate. This section describes the basic steps used to create a simple application by using Visual Basic version 5.0 and the Player control. This section assumes the reader has some knowledge of Visual Basic and the Visual Basic version 5.0 development environment.

Getting Started

If the Player control is properly installed on your system, the Visual Basic development environment provides an easy procedure for installing the control into your project's toolbox. The control is listed as the Microsoft Media Player on the Controls tab of the Components dialog box.

This simple sample assumes that your project is a standard executable with one form. Try the following steps to create your own Visual Basic Player application.

Inserting the Player Control

Add the player control to the form. Change the FileName property to a multimedia file on your computer (for example C:\ASFRoot\Welcome.asf). Change the AutoStart property to False, and the AutoRewind property to True. Because we are adding our own simple user interface to the form, change the ShowControls property to False.

Adding Button Controls

Add three CommandButton controls to your form below the Player control object. Change the caption on the first button to Start, the second button to Stop, and the third button to About. Then add the following code to the form:

Private Sub Command1_Click()
    MediaPlayer1.Play
End Sub
Private Sub Command2_Click()
    MediaPlayer1.Stop
End Sub
Private Sub Command3_Click()
    MediaPlayer1.AboutBox
End Sub

Compiling and Running

Start your application and check the results. If you specified a valid multimedia file in the FileName property, clicking the play button should start the presentation. Clicking the Stop button should stop the presentation.

The About button displays a dialog box containing the version number of the Player control.


Player Control Features

The Media Player control exposes a wide variety of methods, properties, and events for creating entertaining, customized applications and Web pages. This section groups the control's attributes into categories by functionality. Player control attributes can be grouped into the following categories:

  • Playback. These methods and properties can be used to manage the play of multimedia content. They include the ability to start, stop, pause, fast forward, and rewind streams, as well as to mute audio and adjust volume.
  • User Interface. These properties allow you to tailor the display of the operational controls.
  • Content Information. These properties contain information about the title being streamed to the player.
  • Stream Status. These properties and events provide information about the current state and reception quality of the stream, as well as network connections, bandwidth, and buffering.
  • Mouse and Keyboard. These properties and events allow you to capture mouse and keyboard input.
  • Error Handling. These properties are provided to allow your code to respond gracefully to errors and warnings.

This section also contains information on processing script commands embedded into multimedia streams.

Playback Methods and Properties

The Media Player control provides two techniques for specifying the multimedia content to be played. You can set the FileName property or use the Open method. Setting the FileName property to the URL of the desired title will begin playing that title if the AutoStart property is True. If AutoStart is False, the player control does not start playback until the Play method is called. The Open method starts the stream asynchronously, unlike the Play method, which waits for other processes to complete before starting.

The Media Player control provides the following VCR-like attributes for controlling stream playback:

  • Play, Stop, and Pause methods, to start, stop, and pause the stream.
  • PlayCount property to set the number of times a file plays.
  • AutoRewind property to determine whether or not to return to the start of the title when it stops playing.
  • Balance, Volume and Mute properties to control audio.
  • FastForward and FastReverse methods, the Rate, CurrentPosition, CanScan, and AllowScan properties, as well as the PositionChange event, to scan forward and backward through titles.

Some types of multimedia streams support seeking to a given presentation time, or to markers. Markers are pointers to a specific time in a multimedia stream file. The player can seek directly to the time specified by each marker. This enables viewers to skip ahead or skip back to a previous marker to view a portion of the presentation again. Control attributes supported for seeking to a given time and/or seeking to markers include:

  • CanSeek and CanSeekToMarkers properties determine if seeking is permitted for the current presentation.
  • MarkerCount property is used to determine the total number of markers in the file.
  • CurrentMarker, GetMarkerName and GetMarkerTime methods for retrieving marker information.
  • MarkerHit event to provide notification when a marker is encountered.

Attributes for Customizing the User Interface

The Player control exposes a variety of properties and methods for building a custom user interface. Many of these properties can be set at design time to restrict the setting of user interface properties available at run time. These properties may also determine whether or not a corresponding item can be changed by end users on the context menu that is available when the EnableContextMenu property is True.

The following properties determine the appearance of the control before a title starts playing:

  • TransparentAtStart
  • AnimationAtStart

The following properties are exposed for displaying various elements of the built-in user interface:

  • ShowControls

  • ShowAudioControls

  • ShowDisplay

  • ShowGotoBar

  • ShowPositionControls

  • ShowStatusBar

  • ShowTracker

The border that is displayed around the control is determined by the state of the following properties:

  • VideoBorder3d

  • VideoBorderWidth

  • VideoBorderColor

The control exposes the following properties used to change the size of the image being played:

  • AllowChangeDisplaySize determines whether or not the DisplaySize property can be set.

Title Information Properties

Some types of multimedia streams contain metadata detailing show and clip information. The GetMediaInfoString method can be used to retrieve the following information about the clip and show:

  • File name
  • Title
  • Description
  • Author
  • Copyright
  • Rating

GetmediaInfoString also provides information about the current banner and watermark.

The following properties return information about the size and duration of the presentation:

  • The ImageSourceHeight and ImageSourceWidth properties return the display size of the image window.
  • Duration. You can determine if this property contains valid data by checking the value of the IsDurationValid property.

The player also supports Synchronized Accessible Media Interchange (SAMI) for closed captioning. Properties exposed by the Player control for SAMI captioning support include:

  • SAMIFileName
  • SAMILang
  • SAMIStyle
  • CaptionID
  • ShowCaptioning

Monitoring Stream Status and Network Reception

Stream status properties include:

  • PlayState
  • OpenState

Bandwidth Supported events include:

  • OpenStateChange. Fired only when the SendOpenStateChangeEvents property is True.
  • PlayStateChange. Fired only when the SendPlayStateChangeEvents property is True.
  • EndOfStream

NewStream Network reception attributes include:

  • ReceptionQuality
  • ReceivedPackets

LostPackets Attributes for monitoring buffering include:

  • BufferingTime property
  • BufferingCount property
  • BufferingProgress property
  • Buffering event

Multicast ASF streams also contain information about the channel being used for the multicast. Channel attributes include:

  • ChannelDescription property
  • ChannelName property
  • ChannelURL property

Each channel has a contact that is responsible for the multicast. Channel contact attributes include:

  • ContactAddress property
  • ContactEmail property
  • ContactPhone property

Capturing Keyboard and Mouse Events

The EnableContextMenu and ClickToPlay properties provide for user input through the image window. If EnableContextMenu is True, the user gets a context menu that gives them access to many of the control's properties. If the ClickToPlay property is True, users can start the player by clicking on the image window.

To receive mouse movement and click events, the SendMouseMoveEvents and SendMouseClickEvents properties must be True. Mouse events include;

  • MouseUp
  • MouseDown
  • MouseMove
  • Click
  • DblClick

To receive keyboard events, SendKeyBoardEvents must be True. Keyboard events include;

  • KeyUp
  • KeyDown
  • KeyPress.

Error Handling

The SendErrorEvents and SendWarningEvents properties must be True to receive errors and warnings. Error handling and warning events supported by the Media Player control include:

  • Error

Warning Error handling properties exposed by the control include:

  • ErrorCode
  • ErrorCorrection
  • ErrorDescription
  • HasError
  • SendErrorEvents
  • SendWarningEvents


Processing Embedded Script Commands

One compelling feature of ASF streams is the script commands that can be delivered to the Media Player control along with the audio and video streams. These script commands are a pair of Unicode strings synchronized with a particular time in the multimedia stream. The first string identifies the type of command being sent, and the second specifies the type-specific command to process. When the stream reaches the time associated with a command, the Player control sends a ScriptCommand event to the container. An event-handling routine can be written to respond to this event. The script-command strings are passed to the event handler as parameters of the ScriptCommand event.

Two types of embedded script commands, URL and FILENAME, are automatically processed by the Player control. Event-handling routines are not needed to process commands with URL and FILENAME types.

URL-type Commands

URL script command types are launched by the default Web browser when they are received by the Player control. If the control is embedded in an HTML page that employs frames, the URL can be launched in a frame specified by the script command. This allows the control to continue rendering the multimedia stream in one frame while the Web browser renders images or Web pages in another frame. If the frame is not specified in the script command, the DefaultFrame property determines which frame the new URL is launched in.

Note: If frames are not used, or if the URL-type command is launched in the same frame as the Player control, the page rendering the stream is replaced by the URL specified by the script command.

Automatic processing of URL-type script commands can be enabled or disabled by setting the InvokeURLs property. If this property is set to FALSE, the URL-type command is ignored by the control; however, the ScriptCommand event is still sent to the container.

URL-type script commands specify the relative location of the URL. A base HTTP URL can be specified by the BaseURL property. The Player control concatenates the base URL with the relative URL. The result is a fully specified URL that is passed as the command parameter of the ScriptCommand event.

FILENAME-type Commands

When a script command with the FILENAME type is received by the Player control, the FileName property is set to the value specified by the command. Then the control opens the file and begins rendering the stream from the new location. The control always automatically processes FILENAME-type commands; they can not be disabled like URL-type commands.


Media Player Control Reference

This section lists the events, methods, and properties supported by the Media Player control.


Player Control Properties

The control supports the following properties.

Property | Description
AllowChangeDisplaySize | Returns or sets a Boolean value determining whether the end-user can set the display size.
AllowScan | Returns or sets a Boolean value determining whether scanning is enabled.
AnimationAtStart | Returns or sets a Boolean value determining whether the control plays an animated sequence before the title begins streaming.
AudioStream | Returns or sets a Long value indicating the audio stream number.
AutoRewind | Returns or sets a Boolean value determining whether a title is rewound at the end of playback.
AutoSize | Returns a or sets a Boolean value indicating whether to size the control automatically to accommodate the loaded media.
AutoStart | Returns or sets a Boolean value determining whether to automatically start playing the title.
Balance | Returns or sets a Long value indicating the stereo balance.
Bandwidth | Returns the a Long value indicating the bandwidth of the current title.
BaseURL | Returns a String value indicating the base HTTP URL.
BufferingCount | Returns a Long value indicating the number of times buffering occurred during the title’s playback.
BufferingProgress | Returns a Long value indicating the percentage of buffering completed.
BufferingTime | Returns a Double value indicating the buffering time.
CanPreview | Returns a Boolean value determining whether or not the clips in the current show can be viewed in preview mode.
CanScan | Returns a Boolean value determining whether the current file supports fast forward and fast reverse.
CanSeek | Returns a Boolean value determining whether the current file has the ability to seek to a specific time.
CanSeekToMarkers | Returns a Boolean value determining whether markers in the file can be located with a seek operation.
CaptioningID | Returns a String value indicating the name of the frame or control displaying the captioning.
ChannelDescription | Returns a String value indicating the station’s description.
ChannelName | Returns a String value indicating the station’s name.
ChannelURL | Returns a String value indicating the location of the station’s metafile.
ClickToPlay | Returns or sets a String value indicating whether the title can be paused or played by clicking on the image.
ClientID | Returns a String value specifying a unique identifier for the client.
CodecCount | Returns a Long value indicating the number of installable codecs used by the file.
ContactAddress | Returns a String value indicating the station’s contact address.
ContactEmail | Returns a String value indicating the station’s contact e-mail address.
ContactPhone | Returns a String value indicating the station’s contact telephone number.
CreationDate | Returns a Date value indicating the title’s creation date.
CurrentMarker | Returns or sets a Long value indicating the current marker number.
CurrentPosition | Returns or sets a Double value indicating the title’s current position.
CursorType | Returns or sets a Long value indicating the cursor type.
DefaultFrame | Returns or sets a String value indicating the control’s default target HTTP frame.
DisplayBackColor | Returns or sets an OLE_COLOR value indicating the display panel's background color.
DisplayForeColor | Returns or sets an OLE_COLOR value indicating the display panel's foreground color.
DisplayMode | Returns or sets an MPDisplayModeConstants value indicating whether the display panel shows the current position in seconds or frames.
DisplaySize | Returns or sets an MPDisplaySizeConstant value indicating the size of the image display window.
Duration | Returns or sets a Double value indicating the title’s playing time.
EnableContextMenu | Returns or sets a Boolean value indicating whether to enable the context menu.
Enabled | Returns or sets a Boolean value indicating whether the control is enabled.
EnableFullScreenControls | Returns or sets a Boolean value indicating whether full screen controls are enabled.
EnablePositionControls | Returns or sets a Boolean value indicating whether to enable position controls.
EnableTracker | Returns or sets a Boolean value indicating whether to enable the trackbar controls.
ErrorCode | Returns a Long value indicating the current error code.
ErrorCorrection | Returns a Long value indicating the error correction type of the current title.
ErrorDescription | Returns a String value indicating the current error description.
FileName | Returns or sets a String value that indicates or sets the name of the title to play.
HasError | Returns a Boolean value indicating whether the control currently has an error.
HasMultipleItems | Returns a Boolean value indicating whether the control has something that contains multiple items.
ImageSourceHeight | Returns a Long value indicating the current title’s original image height.
ImageSourceWidth | Returns a Long value indicating the current title’s original image width.
InvokeURLs | Returns or sets a Boolean value indicating whether URLs are automatically invoked.
IsBroadcast | Returns a Boolean value indicating whether the source is a broadcast.
IsDurationValid | Returns a Boolean value indicating whether the Duration value is valid.
Language | Returns or sets a Long value specifying the current locale used for local language support.
LostPackets | Returns a Long value indicating the number of packets lost.
MarkerCount | Returns a Long value indicating the number of file markers.
Mute | Returns or sets a Boolean value indicating whether the control plays sound.
OpenState | Returns a Long value indicating the state of the control’s content source.
PlayCount | Returns or sets a Long value indicating the number of times a title plays.
PlayState | Returns a Long value indicating the state of the control’s operation.
PreviewMode | Returns or sets a Boolean value indicating whether the control is in preview mode.
Rate | Returns or sets a Double value indicating the playback rate.
ReadyState | Returns a ReadyStateConstant value indicating the control's state of readiness.
ReceivedPackets | Returns a Long value indicating the number of packets received.
ReceptionQuality | Returns a Long value indicating the percentage of packets received in the last 30 seconds.
RecoveredPackets | Returns a Long value indicating the number of packets recovered.
SAMIFileName | Returns or sets a String value indicating the closed-captioning filename.
SAMILang | Returns or sets a String value indicating the closed captioning language.
SAMIStyle | Returns or sets a String value indicating the closed captioning style.
SelectionEnd | Returns or sets a Double value indicating the ending position of a stream.
SelectionStart | Returns or sets a Double value indicating the beginning position of a stream.
SendErrorEvents | Returns or sets a Boolean value indicating whether the control sends error events.
SendKeyboardEvents | Returns or sets a Boolean value indicating whether the control sends keyboard events.
SendMouseClickEvents | Returns or sets a Boolean value indicating whether the control sends mouse click events.
SendMouseMoveEvents | Returns or sets a Boolean value indicating whether the control sends mouse move events.
SendOpenStateChangeEvents | Returns or sets a Boolean value indicating whether the control sends open state change events.
SendPlayStateChangeEvents | Returns or sets a Boolean value indicating whether the control sends play state change events.
SendWarningEvents | Returns or sets a Boolean value indicating whether the control sends warning events.
ShowAudioControls | Returns or sets a Boolean value indicating whether to show the audio controls.
ShowCaptioning | Returns or sets a Boolean value indicating whether to display captioning.
ShowControls | Returns or sets a Boolean value indicating whether the control panel is visible.
ShowDisplay | Returns or sets a Boolean value indicating whether to show the display panel.
ShowGotoBar | Returns or sets a Boolean value indicating whether to display the goto bar.
ShowPositionControls | Returns or sets a Boolean value indicating whether to display position controls.
ShowStatusBar | Returns or sets a Boolean value indicating whether to display the status bar.
ShowTracker | Returns or sets a Boolean value indicating whether to show the trackbar.
SourceLink | Returns a String value indicating the path to the content file.
SourceProtocol | Returns a Long value indicating the protocol used to receive data.
StreamCount | Returns a Long value indicating the number of media streams.
TransparentAtStart | Returns or sets a Boolean value indicating whether the control is transparent before play begins and after it stops.
VideoBorder3D | Returns or sets a Boolean value indicating whether the video border 3D effect is enabled.
VideoBorderColor | Returns or sets an OLE_COLOR value indicating the color of the video border.
VideoBorderWidth | Returns or sets a Long value specifying the width of the video border.
Volume | Returns or sets a Long value specifying the volume.


AllowChangeDisplaySize

Returns or sets a Boolean value specifying whether or not the end-user can set the display size.

Syntax

MediaPlayer.AllowChangeDisplaySize

Settings

The AllowChangeDisplaySize property can have the following values:

Setting | Description
True | (Default) Allows the user to change the display size.
False | Prevents user from changing the display size.

Remarks

This property determines whether or not the DisplaySize property can be set at run-time. In addition, setting the AllowChangeDisplaySize property to True, allows the end-user to specify the size by clicking Video Size on the context menu.

See Also

DisplaySize


AllowScan

AllowScan Property

Returns or sets a Boolean value specifying whether or not scanning is enabled for files that support scanning (fast forwarding and rewinding).

Syntax

MediaPlayer.AllowScan

Settings

The AllowScan property can have the following values:

Value | Description
True | (Default) Enables file scanning.
False | Disables file scanning.

Remarks

This property determines whether or not the FastForward and FastReverse methods are enabled. In addition, if this property is True, the end-user can scan forward or back through a title by clicking Scan Forward or Scan Rewind on the context menu. While scanning, the position on the trackbar moves rapidly forward or backward. To stop scanning, click Play, Stop, or Pause.

If AllowScan is set to False, the user cannot fast forward or rewind through a file. Scanning requires more CPU usage than normal playback.

Note: Only certain types of files can be scanned, regardless of the value of AllowScan. The CanScan property returns a Boolean value specifying whether or not the file is scannable.

See Also

CanScan


AnimationAtStart

AnimationAtStart Property

Returns or sets a Boolean value specifying whether or not animation runs before the first image displays.

Syntax

MediaPlayer.AnimationAtStart

Settings

The settings for this property are:

Value | Description
True | (Default) Animation plays at start.
False | Disables animation.

Remarks

Setting AnimationAtStart to True makes the image display window play a short animation when a title is buffering and loading. If TransparentAtStart is True, the AnimationAtStart property is ignored.

See Also

Stop, AutoRewind, TransparentAtStart


AudioStream

AudioStream Property

Returns or sets a Long value specifying the stream number of the current audio stream.

Syntax

MediaPlayer.AudioStream

Remarks

This property is useful if your content contains multiple audio streams. For instance, a title may contain several audio streams encoded in different languages. The AudioStream property can be used to specify which language is used when the content is rendered.

See Also

StreamCount


AutoRewind

AutoRewind Property

Returns or sets a Boolean value specifying whether or not to automatically return to the title’s starting point after it has finished playing or has otherwise stopped.

Syntax

MediaPlayer.AutoRewind

Remarks

This property has the following values:

Value | Description
True | (Default) Title rewinds automatically upon completion or stop.
False | Disables automatic rewind.

To retain the current position within the title, set AutoRewind to False, or use the Pause method.

The default behavior is to keep the current position at the end of the file after it is played, with the last image still showing. Setting AutoRewind to True will return the current position to zero after playing.

The state of the image display window after automatic rewinding is determined by other Player control properties. The default behavior is to display the background color of the control. If TransparentAtStart is True, after the file finishes playing, the control will become transparent. If AnimationAtStart is True (and TransparentAtStart is False), the title image is shown.

If PlayCount is greater than 1, the current position is returned to 0 (zero) only after the file is played PlayCount times. Between plays, the last image of the file is shown while play is restarting.

See Also

AutoStart, CurrentPosition


AutoSize Property

This property returns a Boolean value indicating whether or not the player control will automatically size to the proportions of the original media.

Syntax

MediaPlayer.AutoSize

Remarks

The values for this property are:

Value | Description
True | The player changes size to conform to the size of the content.
False | The player retains the width and height set at design time..

The default value for this property is True if no width and height parameters are set at design-time, otherwise it defaults to False. Visual Basic automatically sets the width and height of the control at design-time.


AutoStart

AutoStart Property

Returns or sets a Boolean value specifying whether or not to automatically start playing the title.

Syntax

MediaPlayer.AutoStart

Remarks

The settings for this property are:

Value | Description
True | (Default) Title automatically starts.
False | Disables automatic start.

If you set this property to True, the title automatically starts playing when the Filename property is set or the Open method is called. If you set this property to False, the player does not start the file until the Play method is called or the Play button is pressed.

See Also

FileName, PlayCount, Play


Balance

Balance Property

Returns or sets a Long value indicating the stereo balance.

Syntax

MediaPlayer.Balance

Remarks

The default value 0 indicates that the sound is balanced equally between the left and right speakers. A value of –10,000 indicates that all sound is going to the left speaker and 10,000 that all sound is going to the right speaker.

See Also

Volume


Bandwidth

Bandwidth Property

Returns a Long value specifying the bandwidth of the current title in bits per second.

Syntax

MediaPlayer.Bandwidth

Remarks

This property returns 0 (zero) if the FileName property is not set. This property is only valid for streaming media.


BaseURL

BaseURL Property

Returns or sets a String value specifying the base HTTP URL.

Syntax

MediaPlayer.BaseURL

Remarks

Commands can be embedded among the sounds and images of an .asf file. The commands are a pair of Unicode strings associated with a designated time in the stream. When the stream reaches the time associated with the command, the Media Player control sends a ScriptCommand event with two parameters: one parameter specifying the type of command being sent, and one parameter specifying the command. The type parameter is used to determine how the command parameter will be processed. Any type of command can be embedded in an ASF stream to be handled by the ScriptCommand event.

One type of command is a URL (Uniform Resource Locator). URLs received by the Player control are invoked automatically in your default Internet browser if the InvokeURLs property is True.

The URL sent to the control is processed relative to the base URL specified by this property. The base URL is concatenated with the relatively specified URL, resulting in a fully specified URL that is passed as the command parameter by the ScriptCommand event. The base URL is concatenated with the relative URL as follows:

  1. A trailing forward slash ('/') is added to the value of the BaseURL property.

  2. Leading period, backward slash, and forward slash characters ('.', '\', and '/') are deleted from the relative URL.

  3. The relative URL is added to the end of the base URL.

  4. All slashes in the resulting fully qualified URL are pointed in the same direction (converted to forward or backward slashes) based on the direction of the first slash character encountered in the new URL.

Note: The Player control does NOT support the use of two periods ('..') in the relative URL to indicate the parent of the current location.

See Also

ScriptCommand event, DefaultFrame property


BufferingCount

BufferingCount Property

Returns a Long value specifying the number of times buffering occurred during the title’s playback.

Syntax

MediaPlayer.BufferingCount

Remarks

Each time playback is stopped and restarted, this property is set to zero. It is not reset if playback is paused.

Buffering only applies to streaming content. This property returns valid information only during run time when the FileName property is set.

See Also

Buffering, BufferingProgress, BufferingTime


BufferingProgress

BufferingProgress Property

Returns a Long value specifying the percentage of buffering completed.

Syntax

MediaPlayer.BufferingProgress

Remarks

Each time playback is stopped and restarted, this property is set to zero. It is not reset if playback is paused.

Buffering only applies to streaming content. This property returns valid information only during run time, when the FileName property is set.

See Also

Buffering, BufferingCount, BufferingTime


BufferingTime

BufferingTime Property

Returns a Double value specifying the buffering time.

Syntax

MediaPlayer.BufferingTime

Remarks

The buffering time is the number of seconds that the Media Player control allocates for buffering incoming data before playing begins.

The valid range for this property is from 1 through 30 seconds. The default for ASF content is 5 seconds. The default for VOD content is 3 seconds.

See Also

Buffering, BufferingCount, BufferingProgress


CanPreview

CanPreview Property

Returns a Boolean value indicating whether or not the current content contains a play list that can be previewed.

Syntax

MediaPlayer.CanPreview

Remarks

If this property is TRUE, the control can be operated in preview mode by setting the PreviewMode property to TRUE. When the control is in preview mode, a few seconds of each clip in the play list is rendered. By default, the length of time each clip plays is 10 seconds; however, the preview duration can be set in the .asx file.

The default value for this property is False.

See Also

PreviewMode


CanScan

CanScan Property

Returns a Boolean value specifying whether or not the current file supports scanning.

Syntax

MediaPlayer.CanScan

Remarks

If True, the current file can be scanned (fast forwarded or fast reverse), provided that the AllowScan property is also set to True.

This property returns False if FileName is not set, or the Open method has not been called.

VOD and ASF both support scanning; however, ASF content can be scanned only if the following conditions are all true:

  • The file is indexed.
  • The file is playing from a NetShow unicast server (not playing locally).
  • The file is not being broadcast.

See Also

AllowScan


CanSeek

CanSeek Property

Returns a Boolean value specifying whether the current file has the ability to seek to a specific time.

Syntax

MediaPlayer.CanSeek

Remarks

Seeking is accomplished by sliding the position indicator on the control or by setting either the CurrentMarker or the CurrentPosition property.

This property returns False if FileName is not set or the Open method has not been called.


CanSeekToMarkers

CanSeekToMarkers Property

Returns a Boolean value specifying whether or not markers in the file can be located with a seek operation.

Syntax

MediaPlayer.CanSeek

Remarks

You can seek to a marker only if the file contains markers and it is stored either locally or on a NetShow unicast server (not on an HTTP server or broadcast by using multicast routing).

Seeking by marker is accomplished by using the Next Marker and Previous Marker buttons in the Player application, or by using the CurrentMarker property.

This property returns False if FileName is not set.


CaptioningID

CaptioningID Property

Returns or sets a String of the name of the frame or control displaying the captioning.

Syntax

MediaPlayer.CaptioningID


ChannelDescription

ChannelDescription Property

Returns a String value of the station’s description.

Syntax

MediaPlayer.ChannelDescription

Remarks

This property only pertains to ASF content being multicast.


ChannelName

ChannelName Property

Returns a String value indicating of the station name.

Syntax

MediaPlayer.ChannelName

Remarks

This property only pertains to ASF content being multicast.


ChannelURL

ChannelURL Property

Returns a String value of the location of the station metafile.

Syntax

MediaPlayer.ChannelURL

Remarks

Remarks

This property only pertains to ASF content being multicast.

The station URL is the Uniform Resource Locator to the NetShow station (.nsc) file. The station URL follows the syntax of typical URLs, except that it can also include the version number, which is separated from the rest of a URL with a # (pound sign). For example, a station URL might be:

http://myserver/myfile.nsc#54

where 54 is the version desired. If the version of the .nsc file is on the local computer, a new .nsc file is not downloaded.


ClickToPlay

ClickToPlay Property

Returns or sets a Boolean value specifying whether or not the title can be paused or played by clicking on the image.

Syntax

MediaPlayer.ClickToPlay

Settings

The settings for this property are:

Setting | Description
True | (Default) Enables playback toggling.
False | Disables playback toggling.

Remarks

If ClickToPlay is True, clicking anywhere on the image display window toggles playback. If a title is already playing, a mouse click pauses playback. If a title is paused, a mouse click starts playback again.


ClientID Property

This property returns a String value indicating the unique ID of a client.

Syntax

MediaPlayer.ClientID


CodecCount

CodecCount Property

Returns a Long value specifying the number of installable codecs used by the file.

Syntax

MediaPlayer.CodecCount

See Also

GetCodecInstalled, GetCodecDescription, GetCodecURL


ContactAddress

ContactAddress Property

Returns a String value of the station’s contact address.

Syntax

MediaPlayer.ContactAddress

Remarks

This property only pertains to ASF content being multicast. A station is the defined location (IP Address and port) from which a player can receive streams.


ContactEmail

ContactEmail Property

Returns a String value of the station’s email address.

Syntax

MediaPlayer.ContactEmail

Remarks

This property only pertains to ASF content being multicast. A station is the defined location (IP Address and port) from which a player can receive streams.


ContactPhone

ContactPhone Property

Returns a String value of the station’s contact telephone number.

Syntax

MediaPlayer.ContactPhone

Remarks

This property only pertains to ASF content being multicast. A station is the defined location (IP Address and port) from which a player can receive streams.


CreationDate

CreationDate Property

Returns a Date value specifying the date and time the title was created.

Syntax

MediaPlayer.CreationDate

Remarks

If FileName is not set, this property does not return valid data.

See Also

GetMediaInfoString


CurrentMarker

CurrentMarker Property

Returns or sets a Long value indicating the current marker number.

Syntax

MediaPlayer.CurrentMarker

Remarks

Before attempting to set CurrentMarker, determine whether a file has markers and their number by using MarkerCount. If a file has no markers, setting CurrentMarker to anything but zero results in an error. Setting CurrentMarker to a number higher than MarkerCount also results in an error.

CurrentMarker always returns the current or last marker, which means the actual file position may be either at the current marker or before the next marker. Markers are numbered beginning at one, so if a file has markers, you can set CurrentMarker to zero to change the file position to zero.

The current file must be stopped before you can set CurrentMarker.

Before FileName is set, CurrentMarker returns zero.


CurrentPosition

CurrentPosition Property

Returns or sets a Double value of the title’s current position, in seconds.

Syntax

MediaPlayer.CurrentPosition

Settings

The value of this property is a new position within the title, in seconds.

Remarks

Setting the CurrentPosition property at run time is similar to a seek operation, and changes the position to the specified point in the title.

Before attempting to set CurrentPosition, determine the length of the file in seconds by using Duration.

Before FileName is set, CurrentPosition returns zero.

The new value must be within the range specified by the SelectionStart and SelectionEnd properties.

The current position value displayed by the control's user interface can represent either seconds or frames. The DisplayMode property determines the units shown.

Example

This example shows how to use the CurrentPosition property to rewind a title after it has been stopped:

MediaPlayer1.Stop
MediaPlayer1.CurrentPosition = 0


CursorType

CursorType Property

Returns or sets a Long value specifying the cursor type.

Syntax

MediaPlayer.CursorType

Settings

You can specify the cursor's icon when it is over the control by setting CursorType to any of the stock cursor values from the Microsoft Win32® SDK:

Name | Value | Description
IDC_APPSTARTING | 32650 | Standard arrow and small hourglass
IDC_ARROW | 32512 | Standard arrow
IDC_CROSS | 32515 | Crosshair
IDC_IBEAM | 32513 | Text I-beam
IDC_NO | 32648 | Slashed circle
IDC_SIZEALL | 32646 | Four-pointed arrow
IDC_SIZENESW | 32643 | Double-pointed arrow pointing northeast and southwest
IDC_SIZENS | 32645 | Double-pointed arrow pointing north and south
IDC_SIZENWSE | 32642 | Double-pointed arrow pointing northwest and southeast
IDC_SIZEWE | 32644 | Double-pointed arrow pointing west and east
IDC_UPARROW | 32516 | Vertical arrow
IDC_WAIT | 32514 | Hourglass
IDC_HAND | 1 | Hand with pointing index finger

Note IDC_HAND is not a stock cursor, but is included with the control.

The default value of this property is 0, which represents a hand with a pointing index finger if no file is loaded, and a standard arrow if a file is loaded.

If ClickToPlay is True, the arrow changes to a hand when it is over the image display window to signify a click option to the user.

See Also

ClickToPlay


DefaultFrame

DefaultFrame Property

Returns or sets a String value of the control's default target HTTP frame.

Syntax

MediaPlayer.DefaultFrame

Remarks

This property specifies which frame flips to display a new location when a URL type ScriptCommand event occurs. If the frame is specified in the ScriptCommand event, this property is ignored.

See Also

ScriptCommand event, InvokeURLs property, BaseURL property


DisplayBackColor

DisplayBackColor Property

Returns or sets a Long value specifying the display panel's background color.

Syntax

MediaPlayer.DisplayBackColor

Remarks

At design time, the default setting is black (0x0).

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte is not 0, Visual Basic uses the system colors, as defined in the user's Control Panel settings, and by constants listed in the Object Browser's object library.

Settings

The DisplayBackColor property can have the following values:

Setting | Description
Normal RGB colors | Colors specified by using the color palette or by using the Visual Basic RGB or QBColor functions in code.
System default colors | Colors specified by system color constants listed in the Object Browser's object library. The Microsoft Windows® operating environment substitutes the user's choices as specified in the Control Panel settings.

See Also

DisplayForeColor


DisplayForeColor

DisplayForeColor Property

Returns or sets a Long value specifying the display panel's foreground color.

Syntax

MediaPlayer.DisplayForeColor

Remarks

At design time, the default setting is white (&HFFFFFF).

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte is not 0, Visual Basic uses the system colors, as defined in the user's Control Panel settings, and by constants listed in the Object Browser's object library.

Settings

The DisplayForeColor property can have the following values:

Setting | Description
Normal RGB colors | Colors specified by using the color palette or by using the Visual Basic RGB or QBColor functions in code.
System default colors | Colors specified by system color constants listed in the Object Browser's object library. The Windows operating environment substitutes the user's choices as specified in the Control Panel settings.

See Also

DisplayBackColor


DisplayMode

DisplayMode Property

Returns or sets an Integer value specifying whether the status bar displays the current position in seconds or frames.

Syntax

MediaPlayer.DisplayMode

Remarks

The DisplayMode property can have the following values:

Setting | Description
0 | (Default) Display the current position in seconds.
1 | Display the current position in frames.

This property only works with local playback content.

See Also

DisplayModeChange event, ShowDisplay property


DisplaySize

DisplaySize Property

Returns or sets a Long value specifying the size of the image display window.

Syntax

MediaPlayer.DisplaySize

Remarks

This property can only be set if the AllowChangeDisplaySize property is True.

Valid values for the DisplaySize property include:

Constant | Value | Description
mpDefaultSize | 0 | Same size as the source image.
mpHalfSize | 1 | Half the size of the source image.
mpDoubleSize | 2 | Double the size of the source image.
mpFullScreen | 3 | Size of the entire screen.
mpFitToSize | 4 | Size specified at design time.
mpOneSixteenthScreen | 5 | One-sixteenth the size of the screen.
mpOneFourthScreen | 6 | One quarter the size of the screen.
mpOneHalfScreen | 7 | Half the size of the screen.

See Also

AllowChangeDisplaySize


Duration

Duration Property

Returns a Double value indicating the title’s playing time in seconds.

Syntax

MediaPlayer.Duration

Remarks

The IsDurationValid property specifies whether or not this property returns a valid value.

If the FileName property is not set, this property returns 0 (zero).


EnableContextMenu

EnableContextMenu Property

Returns or sets a Boolean value specifying whether or not to enable the control's context menu appears when the right mouse button is clicked.

Syntax

MediaPlayer.EnableContextMenu

Settings

The settings for this property are:

Setting | Description
True | (Default) Enables context menu pop-up.
False | Disables context menu.

Remarks

The context menu appears when the end-user right-clicks anywhere on the control.

The context menu contains commands that would usually be available to the user as buttons (Play/Pause, Stop, Properties, and so on). If a user interface button is disabled, that function is also disabled on the context menu.

A right mouse click anywhere on the control brings up the context menu.

Note: You can set this property only at design time.


Enabled

Enabled Property

Returns or sets an Integer value specifying whether or not the control is enabled.

Syntax

MediaPlayer.Enabled

Remarks

This property is identical to the standard Visual Basic Enabled property.

A disabled control remains visible (if it already was) and will continue to play, if it was already playing. When a control is disabled, none of the commands or menus respond to user input.

Disabling a control at design time is useful if you want to control the media stream from an external source, such as a custom group of controls on a Web page, instead of from the built-in controls panel.

Settings

The Enabled property can have the following values:

Setting | Description
True | (Default) The control is enabled.
False | The control is disabled.


EnableFullScreenControls Property

Description

This property returns or sets a Boolean value indicating whether the player should display controls when it is shown full size.

Syntax

MediaPlayer.EnableFullScreenControls

Remarks

This property has the following values:

Setting | Description
True | (Default) Full screen controls are enabled.
False | Full screen controls are disabled.


EnablePositionControls

EnablePositionControls Property

Returns or sets a Boolean value specifying whether or not the position buttons on the controls panel are enabled.

Syntax

MediaPlayer.EnablePositionControls

Settings

The EnablePositionControls property can have the following values:

Setting | Description
True | (Default) The position controls are enabled.
False | The position controls are disabled.

See Also

ShowPositionControls


EnableTracker

EnableTracker Property

Returns or sets a Boolean value specifying whether or not the trackbar control is enabled.

Syntax

MediaPlayer.EnableTracker

Settings

The EnableTracker property can have the following values:

Setting | Description
True | (Default) The trackbar is enabled.
False | The trackbar is disabled.

See Also

ShowTracker


ErrorCode

ErrorCode Property

Returns a Long value specifying the current error code.

Syntax

MediaPlayer.ErrorCode

See Also

ErrorCorrection, ErrorDescription, HasError, SendErrorEvents


ErrorCorrection

ErrorCorrection Property

Returns a String value specifying the error correction type of the current title.

Syntax

MediaPlayer.ErrorCorrection

Remarks

If FileName is not set, this property returns an empty string.

The settings for this property are:

Setting | Description
Standard | (Default) Stardard error correction.
None | No error correction.

See Also

ErrorCode, ErrorDescription, HasError, SendErrorEvents


ErrorDescription

ErrorDescription Property

Returns a String value specifying the description of the current error state.

Syntax

MediaPlayer.ErrorDescription

See Also

ErrorCode, ErrorCorrection, HasError, SendErrorEvents


FileName

FileName Property

Returns or sets a String value specifying the name of the title to play.

Syntax

MediaPlayer.FileName

Remarks

If the AutoStart property is True, file playback begins automatically anytime you set FileName. If you set both AutoStart and FileName at design time, the control begins playing the file when it is loaded.

See Also

Open method, AutoStart property


HasError

HasError Property

Returns a Boolean value specifying whether or not the control currently has an error.

Syntax

MediaPlayer.HasError

See Also

ErrorCode, ErrorDescription


HasMultipleItems

HasMultipleItems Property

Returns a Boolean value specifying whether or not the current content file contains multiple items (play lists).

Syntax

MediaPlayer.HasMultipleItems

See Also

PreviewMode property, CanPreview property


ImageSourceHeight

ImageSourceHeight Property

Returns a Long value specifying the current title’s original image height in pixels.

Syntax

MediaPlayer.ImageSourceHeight

Remarks

If FileName is not set, this property returns zero.

See Also

ImageSourceWidth


ImageSourceWidth

ImageSourceWidth Property

Returns a Long value specifying the current title’s original image width in pixels.

Syntax

MediaPlayer.ImageSourceWidth

Remarks

If FileName is not set, this property returns zero.

See Also

ImageSourceHeight


InvokeURLs

InvokeURLs Property

Returns or sets a Boolean value specifying whether or not the Media Player control automatically invokes URLs in an Internet or intranet browser.

Syntax

MediaPlayer.InovkeURLs

Remarks

ASF files can contain Uniform Resource Locators (URLs). When a URL is sent to the Player control, it is passed first to the ScriptCommand event, regardless of the value in InvokeURLs. After ScriptCommand exits, the Player control checks InvokeURLs to determine whether or not to start the default Internet browser with the URL. You can selectively display URLs by checking them in ScriptCommand and setting InvokeURLs as desired. For more information, see the ScriptCommand event.

The default value of this property is True.

See Also

ScriptCommand


IsBroadcast

IsBroadcast Property

Returns a Boolean value specifying whether or not the source is a broadcast

Syntax

MediaPlayer.IsBroadcast

Remarks

During a broadcast, Pause is not available.


IsDurationValid

IsDurationValid Property

Returns a Boolean value specifying whether or not the Duration value is valid.

Syntax

MediaPlayer.IsDurationValid

Remarks

During some broadcasts (typically live events), the duration is unknown.


Language

Language Property

Returns or sets a Long value specifying the current locale used for national language support.

Syntax

MediaPlayer.Language

Remarks

The long value correspond LCIDs identify a locale for national language support.


LostPackets

LostPackets Property

Returns a Long value specifying the number of packets lost.

Syntax

MediaPlayer.LostPackets

Remarks

Packets may be lost for a number of reasons, such as the type and quality of the network connection.

Each time playback is stopped and restarted, this property is set to zero. It is not reset if playback is paused and restarted. This property returns valid information only during run time, and only if the FileName property is set.

See Also

ReceivedPackets, RecoveredPackets, ReceptionQuality


MarkerCount

MarkerCount Property

Returns a Long value of number of markers in the content file.

Syntax

MediaPlayer.MarkerCount

Remarks

This property returns zero if a file has no markers, or the FileName property is not set. Marker numbers start at 1.


Mute

Mute Property

Returns or sets a Boolean value indicating the current mute state of the stream.

Syntax

MediaPlayer.Mute

Settings

The Mute property can have the following values:

Value | Description
True | Player volume is muted.
False | (default) Player volume is not muted.


OpenState

OpenState Property

Returns a Long value indicating the state of the control’s content source.

Syntax

MediaPlayer.OpenState

Remarks

Use the open state to determine the status of a request to open a title. The OpenState property can have the following values.

Constatnt | Value | Description
nsClosed | 0 | Content file is closed.
NsLoadingASX | 1 | Loading an .asx redirector file.
NsLoadingNSC | 2 | Loading an .nsc station file.
nsLocating | 3 | Locating the server.
nsConnecting | 4 | Connecting to the server.
nsOpening | 5 | Opening or listening for the stream.
nsOpen | 6 | Content file is open.

Each time the OpenState property changes an OpenStateChange event is fired by the server if the SendOpenStateChange property is True.

See Also

SendOpenStateChangeEvents, OpenStateChange


PlayCount

PlayCount Property

Returns or sets a Long value indicating the number of times a title plays.

Syntax

MediaPlayer.PlayCount

Remarks

If you set this property to zero, the control will play the title repeatedly, restarting as soon as it reaches the end.

The default value of this property is 1.

See Also

AutoStart


PlayState

PlayState Property

Returns a Long value indicating the state of the control’s operation.

Syntax

MediaPlayer.PlayState

Remarks

Use PlayState to determine the status of an open title. The PlayState property can have the following values.

Constant | Value | Description
mpStopped | 0 | Playback is stopped.
mpPaused | 1 | Playback is paused.
mpPlaying | 2 | Stream is playing.
mpWaiting | 3 | Waiting for stream to begin.
mpScanForward | 4 | Stream is scanning forward.
mpScanReverse | 5 | Stream is scanning in reverse.
mpSkipForward | 6 | Skipping to next.
mpSkipReverse | 7 | Skipping to previous
mpClosed | 8 | Stream is not open.

Each time the PlayState property changes, a PlayStateChange event is fired by the server if the SendPlayStateChange property is True.

See Also

SendPlayStateChangeEvents, PlayStateChange


PreviewMode

PreviewMode Property

Returns or sets a Boolean value specifying whether or not the control is in preview mode.

Syntax

MediaPlayer.PreviewMode

Remarks

The PreviewMode property can have the following values:

Value | Description
True | The player is in preview mode.
False | (default) The player is not in preview mode.

The CanPreview property must be True before this property can be set to True.

See Also

CanPreview


Rate

Rate Property

Returns or sets a Double value specifying the title’s playback rate.

Syntax

MediaPlayer.Rate

Remarks

This property acts as a multiplier value that allows you to play the title at a faster or slower rate. The value 1.0 indicates the authored speed and is the default value. Note that the audio track becomes difficult to understand at rates lower than 0.5 and higher than 1.5. A playback rate of 2 equates to twice the normal playback speed.

ASF and VOD: Optimal values for Rate are values x where –10 ≤ x ≤ -1 or 1 ≤ x ≤ 10. Values for Rate with an absolute magnitude greater than 10 are allowable, but not very meaningful. Audio plays only when the Rate value is 1. An .asf or .vod file must be stopped and the AllowScan property must be true before you can set the Rate property. Negative values for Rate indicate reversed playback directions. Rate applies only to files that meet the same conditions as stated in the CanScan section.

Quartz: Rate can be a value x where 0 < x < 9. Negative values for Rate are not allowed. Rate values less than one represent slow-motion. Rate values above 9 are allowable, but not very meaningful.

See Also

CanScan, AllowScan


ReadyState

ReadyState Property

Returns a Long value specifying the control's state of readiness.

Syntax

MediaPlayer.ReadyState

Remarks

The player control changes this property at run time, and its value is passed as a parameter to the ReadyStateChange event.

The Play method will only work on the control after the ReadyState property has reached the mpReadyStateInteractive or mpReadyStateComplete state.

Settings

The ReadyState property can have the following values:

Setting | Value | Description
mpReadyStateUninitialized | 0 | The FileName property has not been initialized.
mpReadyStateLoading | 1 | The player control is asynchronously loading a file.
mpReadyStateInteractive | 3 | The player control loaded a file, and downloaded enough data to play the file, but has not yet received all data.
mpReadyStateComplete | 4 | All data has been downloaded.

See Also

ReadyStateChange event


ReceivedPackets

ReceivedPackets Property

Returns a Long value specifying the number of packets received.

Syntax

MediaPlayer.ReceivedPackets

Remarks

Each time title playback is stopped and restarted, this property is set to zero. It is not reset if file playback is paused.

Note This property returns valid information only during run time and only if the FileName property is also set.

See Also

LostPackets, ReceptionQuality, RecoveredPackets


ReceptionQuality

ReceptionQuality Property

Returns a Long value specifying the percentage of packets received in the last 30 seconds.

Syntax

MediaPlayer.ReceptionQuality

Remarks

The number of packets received, lost, and recovered is monitored every second. ReceptionQuality is the percentage of packets not lost over the last 30 seconds.

Each time file playback is stopped and restarted, this property is set to zero. It is not reset if file playback is paused.

Note This property returns valid information only during run time and only if the FileName property is also set.

See Also

LostPackets, ReceivedPackets, RecoveredPackets


RecoveredPackets

RecoveredPackets Property

Returns a Long value specifying the number of packets recovered.

Syntax

MediaPlayer.RecoveredPackets

Remarks

Each time file playback is stopped and restarted, this property is set to zero. It is not reset if file playback is paused.

Note This property returns valid information only during run time and only if the FileName property is also set.

See Also

LostPackets, ReceivedPackets, ReceptionQuality


SAMIFileName

SAMIFileName Property

Returns or sets a String value indicating name of the file containing the information needed for closed captioning.

Syntax

MediaPlayer.SAMIFileName

Remarks

The Synchronized Accessible Media Interchange (SAMI) file should use an .smi or .sami file extension.

See Also

CaptioningID, SAMIStyle, ShowCaptioning


SAMILang

SAMILang Property

Returns or sets a String specifying the language displayed for closed captioning.

Syntax

MediaPlayer.SAMILang

Remarks

A Synchronized Accessible Media Interchange (SAMI) file can contain text for one or many languages. The languages available for closed captioning are defined between the <Style> and </Style> tags in the SAMI file. A language can be specified by any unique alpha-numeric string that is preceded by a period (.). For example; .ENUSCC, could be used to define US English.

If no SAMI language is specified, the first language defined in the SAMI file is used by default.

See Also

CaptioningID, SAMIStyle, ShowCaptioning


SAMIStyle

SAMIStyle Property

Returns or sets a String of the closed captioning style.

Syntax

MediaPlayer.SAMIStyle

Remarks

A Synchronized Accessible Media Interchange (SAMI) file may contain several format style definitions. SAMI styles are defined between the <Style> and </Style> tags in the SAMI file. A style can be defined by any text string preceded by a pound sign (#). For example; #BigFont, could be used to specify that a larger font will be used.

If no SAMI style is specified, the first style defined in the SAMI file is used by default.

See Also

CaptioningID, SAMILang, ShowCaptioning


SelectionEnd

SelectionEnd Property

Returns or sets a Double value specifying the position where playback of the current presentation will stop.

Syntax

MediaPlayer.SelectionEnd

Remarks

This property specifies the end position in seconds, relative to the start of the presentation. The default value for SelectionEnd is the length of the presentation.

This property can not be set or returned until the ReadyState property has a value of mpReadyStateComplete.

See Also

SelectionStart


SelectionStart

SelectionStart Property

Returns or sets a Double value specifying where playback of the current presentation will begin.

Syntax

MediaPlayer.SelectionStart

Remarks

This property specifies the start position in seconds, relative to the beginning of the presentation. The default value for SelectionStart is zero.

This property can not be set or returned until the ReadyState property has a value of mpReadyStateComplete.

See Also

SelectionEnd


SendErrorEvents

SendErrorEvents Property

Returns or sets a Boolean value specifying whether or not the control sends error events.

Syntax

MediaPlayer.SendErrorEvents

Remarks

Values for this property are:

Value | Description
True | (Default) Error events are enabled.
False | Error events are disabled.

See Also

ErrorCode, ErrorCorrection, ErrorDescription, HasError


SendKeyboardEvents

SendKeyboardEvents Property

Returns or sets a Boolean value specifying whether or not the control sends keyboard events.

Syntax

MediaPlayer.SendKeyboardEvents

Remarks

Values for this property are:

Value | Description
True | Keyboard events are enabled.
False | (Default) Keyboard events are disabled.

Keyboard events are only fired when this property is True and the player control has focus.

Note: Enable keyboard events only if you need to use them, because they incur a slight performance cost.

See Also

KeyDown, KeyPress, KeyUp


SendMouseClickEvents

SendMouseClickEvents Property

Returns or sets a Boolean value specifying whether or not the control sends mouse click events.

Syntax

MediaPlayer.SendMouseClickEvents

Remarks

Values for this property are:

Setting | Description
True | Mouse click events are enabled.
False | (Default) Mouse click events are disabled.

Mouse click events are only fired when this property is True and the player control has focus.

Note: Enable mouse click events only if you need to use them, because they incur a slight performance cost.

See Also

Click, DblClick, MouseDown, MouseUp


SendMouseMoveEvents

SendMouseMoveEvents Property

Returns or sets a Boolean value specifying whether or not the control sends mouse move events.

Syntax

MediaPlayer.SendMouseMoveEvents

Remarks

The settings for this property are:

Setting | Description
True | Mouse move events are enabled.
False | (Default) Mouse move events are disabled.

Mouse move events are only fired when this property is True and the player control has focus.

Note: Enable events only if you need to use them, because they incur a slight performance cost.

See Also

MouseMove


SendOpenStateChangeEvents

SendOpenStateChangeEvents Property

Returns or sets a Boolean value specifying whether or not the control sends open state change events.

Syntax

MediaPlayer.SendOpenStateChangeEvents

Remarks

The settings for this property are:

Setting | Description
True | (Default) The Media Player control sends open state change events.
False | The control does not send open state change events.

See Also

OpenState , OpenStateChange


SendPlayStateChangeEvents

SendPlayStateChangeEvents Property

Returns or sets a Boolean value specifying whether or not the control sends play state change events.

Syntax

MediaPlayer.SendPlayStateChangeEvents

Remarks

The settings for this property are:

Setting | Description
True | (Default) The Media Player control sends play state change events.
False | The control does not send play state change events.

See Also

PlayState, PlayStateChange


SendWarningEvents

SendWarningEvents Property

Returns or sets a Boolean value specifying whether or not the control sends warning events.

Syntax

MediaPlayer.SendWarningEvents

Remarks

Values for this property are:

Setting | Description
True | (Default) The Media Player control sends warning events.
False | The control does not send warning events.

See Also

Warning event


ShowAudioControls

ShowAudioControls Property

Returns or sets a Boolean value indicating whether to show the audio controls.

Syntax

MediaPlayer.ShowAudioControls

Remarks

The ShowAudioControls property can have the following values:

Value | Description
True | (Default) Audio controls will be shown.
False | Audio controls will not be shown.


ShowCaptioning

ShowCaptioning Property

Returns or sets a Boolean value specifying whether or not to display captioning.

Syntax

MediaPlayer.ShowCaptioning

Remarks

The settings for this property are:

Setting | Description
True | The Media Player control displays captioning.
False | (Default) Captioning is disabled.

If the title has been captioned, text of the dialog appears in a window below the image.

See Also

CaptioningID


ShowControls

ShowControls Property

Returns or sets a Boolean value specifying whether or not the controls panel is visible.

Syntax

MediaPlayer.ShowControls

Remarks

The ShowControls property can have the following values:

Setting | Description
True | (Default) The controls panel is visible.
False | The controls panel is not visible.

See Also

ShowDisplay


ShowDisplay

ShowDisplay Property

Returns or sets a Boolean value specifying whether or not the display panel is visible.

Syntax

MediaPlayer.ShowDisplay

Remarks

The ShowDisplay property can have the following values:

Setting | Description
True | (Default) The display panel is visible.
False | The display panel is not visible.

See Also

ShowControls


ShowGotoBar

ShowGotoBar Property

Returns or sets a Boolean value whether or not to display the goto bar.

Syntax

MediaPlayer.ShowGotoBar

Remarks

The ShowGotoBar property can have the following values:

Setting | Description
True | The goto bar is visible.
False | (Default) The goto bar is not visible.

See Also

ShowControls


ShowPositionControls

ShowPositionControls Property

Returns or sets a Boolean value specifying whether or not the position controls are visible.

Syntax

MediaPlayer.ShowPositionControls

Remarks

The ShowPositionControls property can have the following values:

Value | Description
True | (Default) The position controls are visible.
False | The position controls are not visible.

The position controls consist of four buttons:

  • Skip Back: Jumps to the previous clip in the playlist.

  • Rewind: Scans rapidly backward through the current clip.

  • Fast Forward: Scans rapidly forward through the current clip.

  • Skip Forward: Jumps to the next clip in the playlist.

See Also

EnablePositionControls


ShowStatusBar

ShowStatusBar Property

Returns or sets a Boolean value specifying whether or not to display the status bar.

Syntax

MediaPlayer.ShowStatusBar

Remarks

The settings for this property are:

Setting | Description
True | The Media Player control displays the status bar.
False | (Default) Status bar not shown.

The status bar displays status messages, including errors, and the elapsed play time and presentation duration.


ShowTracker

ShowTracker Property

Returns or sets a Boolean value specifying whether or not the trackbar is visible.

Syntax

MediaPlayer.ShowTracker

Settings

The ShowTracker property can have the following values:

Setting | Description
True | (Default) The trackbar is visible.
False | The trackbar is not visible.

See Also

EnableTracker


SourceLink

SourceLink Property

Returns a String specifying the path to the current content file.

Syntax

MediaPlayer.SourceLink

Remarks

Multiple presentation files (clips) can be referenced in one redirector (.asx) file. Use the SourceLink property to determine where the current clip file resides.

This property does not return valid information if FileName has not been set.


SourceProtocol

SourceProtocol Property

Returns a Long value specifying the protocol used to receive data.

Syntax

MediaPlayer.SourceProtocol

Remarks

Valid protocols include the following:

Constant | Value | Description
nsMulticast | 1 | Multicasting with no control connection.
nsMulticastPlus | 2 | Multicasting with control connection.
nsUDP | 3 | User Datagram Protocol
nsTCP | 4 | Transmission Control Protocol
nsDistribution | 5 | MSBD protocol. Typically used to connect directly to the encoder for test purposes.
nsHTTP | 6 | Hyper Text Transport Protocol.
nsFile | 7 | File Transfer Protocol.

See Also

SourceLink


StreamCount

StreamCount Property

Returns a Long value indicating the number of media streams.

Syntax

MediaPlayer.StreamCount

Remarks

This property returns the number of streams in the presentation; however, all of the streams included by this parameter may not be active.


TransparentAtStart

TransparentAtStart Property

Returns or sets a Boolean value specifying whether or not the control is transparent before playing begins.

Syntax

MediaPlayer.TransparentAtStart

Remarks

This property can have the following values:

Value | Description
True | The control is not displayed before play starts and after play ends.
False | (Default) The control is displayed before play starts and after it ends.

When setting TransparentAtStart to True in Visual Basic, the ClipControls property on the parent should be set to False. Otherwise, the background will not repaint.


VideoBorder3D Property

Returns or sets a Boolean value specifying whether or not the 3D video border effect is enabled.

Syntax

MediaPlayer.VideoBorder3D

Remarks

This property can have the following values:

Value | Description
True | The 3D video border is displayed.
False | (Default) The 3D video border is not displayed.

The 3D video border is a one pixel wide

See Also

VideoBorderColor, VideoBorderWidth


VideoBorderColor Property

Returns or sets an OLE_COLOR value specifying the color of the video border.

Syntax

MediaPlayer.VideoBorderColor

See Also

VideoBorder3D, VideoBorderWidth


VideoBorderWidth Property

Returns or sets a Long value specifying the width of the video border, measured in pixels.

Syntax

MediaPlayer.VideoBorderWidth

Remarks

The default value for this property is zero, indicating no video border is displayed.

See Also

VideoBorder3D, VideoBorderColor


Volume

Volume Property

Returns or sets a Long value of the volume, in hundredths of decibels.

Syntax

MediaPlayer.Volume

Remarks

The value ranges from –10,000 to 0 (zero). Zero specifies full volume and –10,000 specifies no volume. The default value for this property is -600.

Not all devices support 10,000 discrete steps of volume.

See Also

Balance


Player Control Methods

The control supports the following methods.

Method | Description
AboutBox | Displays version and copyright information about the control.
Cancel | Cancels the Open method before the file completes opening.
FastForward | Fast forwards the title’s playback.
FastReverse | Rewinds the title’s playback.
GetCodecDescription | Returns the description of the codec currently in use.
GetCodecInstalled | Determines whether a specific codec is installed.
GetCodecURL | Returns the URL for a codec.
GetMarkerName | Returns a marker’s name.
GetMarkerTime | Returns a marker’s time.
GetMediaInfoString | Shows the Information String for the Media.
GetMoreInfoURL | Returns a More Information URL.
GetStreamGroup | Returns a stream group.
GetStreamName | Returns a stream name.
GetStreamSelected | Returns whether the stream is currently selected.
IsSoundCardEnabled | Determines whether the computer's sound card is enabled.
Next | Jumps to the next clip in a playlist.
Open | Asynchronously opens a specified title.
Pause | Suspends title playback at the current position.
Play | Starts playing a title from the starting position or continues playing a paused or stopped title.
Previous | Jumps to the previous clip in a playlist.
Stop | Stops title playback.
StreamSelect | Selects a media stream.


AboutBox

AboutBox Method

Displays version and copyright information about the Media Player control.

Syntax

MediaPlayer.AboutBox

Parameters

This method has no parameters.


Cancel

Cancel Method

Cancels the asynchronous Open method before a title is completely opened.

Syntax

MediaPlayer.Cancel

Parameters

This method has no parameters.

Remarks

This method does not close a connection to a NetShow Theater server. To close a NetShow Theater server connection, set the FileName property to an empty string, as in:

MediaPlayer.FileName = ""

See Also

Open


FastForward

FastForward Method

Scans rapidly forward through the current presentation.

Syntax

MediaPlayer.FastForward

Parameters

This method has no parameters.

Remarks

This method performs the same action as holding down the FastForward button on the playbar. Fast forward can also be achieved by setting the Rate property to a higher value and playing the title.

See Also

FastReverse, Pause, Play, Stop, Rate


FastReverse

FastReverse Method

Scans rapidly backward through the current presentation.

Syntax

MediaPlayer.FastForward

Parameters

This method has no parameters.

Remarks

This method performs the same action as holding down the Rewind button on the playbar. Fast reverse can also be achieved by setting the Rate property to a negative value and playing the title.

See Also

FastForward, Pause, Play, Stop, Rate


GetCodecDescription

GetCodecDescription Method

Returns a String containing the descriptive name of the given codec.

Syntax

MediaPlayer.GetCodecDescription( CodecNum )

Parameters

CodecNum

A Long value specifying the codec number.

Remarks

This property returns a null string if the specified codec is not found.


GetCodecInstalled

GetCodecInstalled Method

Returns a Boolean value specifying whether or not a specific codec is installed.

Syntax

MediaPlayer.GetCodecInstalled( CodecNum )

Parameters

CodecNum

A Long value specifying the codec number.

Remarks

This property returns True if the specified codec is installed, otherwise it returns False.


GetCodecURL

GetCodecURL Method

Returns a String value specifying the URL for a codec.

Syntax

MediaPlayer.GetCodecURL( CodecNum )

Parameters

CodecNum

A Long value specifying the codec number.

Remarks

This property returns a null string if the specified codec is not found.


GetMarkerName

GetMarkerName Method

Returns a String containing the name of the marker, given its marker number.

Syntax

MediaPlayer.GetMarkerName( MarkerNum )

Parameters

MarkerNum

A Long value specifying the number of the marker name to return.

Remarks

This property returns a null string if the specified marker does not exist.

If a file has no markers, MarkerCount is zero. If a file has markers, MarkerCount is greater than zero. Marker numbers start at 1.

Note Not all .asf files have markers. Use MarkerCount to find out how many markers are in the current file.

Example

If MediaPlayer1.MarkerCount > 0 Then
  MsgBox "Marker 1 is named " + MediaPlayer.GetMarkerName(1) + "."
End If

See Also

MarkerCount, CurrentMarker


GetMarkerTime

GetMarkerTime Method

Returns a Double value specifying the presentation time of a given marker.

Syntax

MediaPlayer.GetMarkerTime( MarkerNum )

Parameters

MarkerNum

A Long value specifying the number of the marker to return.

Remarks

To get the time of a marker, set MarkerNum to the number of the marker you want.

If a file has no markers, MarkerCount is zero. If a file has markers, MarkerCount is greater than zero. Marker numbers start at 1.

Note Not all .asf files have markers. Use MarkerCount to find out how many markers are in the current file.

Example

If MediaPlayer.MarkerCount > 0) Then
  MsgBox "Marker 1 is at" + Str$(MediaPlayer.GetMarkerTime(1)) _
   + " seconds."
End If


GetMediaInfoString

GetMediaInfoString Method

Returns a String value containing a description for the given media information type.

Syntax

MediaPlayer.GetMediaInfoString( MediaInfoType )

Parameters

MediaInfoType

A Long value indicating the type of show or clip information to return. Show information refers to an .asx file containing a playlist. Clip information refers to one of the individual media file entries specified in the playlist.

Valid media information types include the following:

Constant | Value | Description
mpShowFilename | 0 | The name of the .asx file containing the playlist.
mpShowTitle | 1 | The playlist's title.
mpShowAuthor | 2 | The playlist's author
mpShowCopyright | 3 | Copyright information for the playlist.
mpShowRating | 4 | Rating information for the playlist.
mpShowDescription | 5 | A description of the playlist.
mpShowLogoIcon | 6 |
mpClipFilename | 7 | The name of the current clip file.
mpClipTitle | 8 | The clip's title.
mpClipAuthor | 9 | The clip's author.
mpClipCopyright | 10 | Copyright information for the clip.
mpClipRating | 11 | Rating information for the clip.
mpClipDescription | 12 | A description of the clip.
mpClipLogoIcon | 13 |
mpBannerImage | 14 |
mpBannerMoreInfo | 15 |
mpWatermark | 16 |


GetMoreInfoURL

GetMoreInfoURL Method

Returns a String value specifying a URL to additional information about the presentation.

Syntax

MediaPlayer.GetMoreInfoURL( MoreInfoType )

Parameters

MoreInfoType

A Long value specifying the type of information contained at the URL location. Supported types include:

Constant | Value | Description
mpShowURL | 0 | More information URL for the show
mpClipURL | 1 | More information URL for the clip.
mpBannerURL | 2 | More information URL for the banner.


GetStreamGroup Method

Returns a Long value indicating the group associated with the given media stream.

Syntax

MediaPlayer.GetStreamGroup( StreamNum )

Parameters

StreamNum

A Long value specifying a stream ID number.

See Also

GetStreamName, GetStreamSelected


GetStreamName Method

Returns a String value indicating the name of the given stream.

Syntax

MediaPlayer.GetStreamName( StreamNum )

Parameters

StreamNum

A Long value specifying a stream ID number.

See Also

GetStreamGroup, GetStreamSelected


GetStreamSelected Method

Returns a Boolean value indicating whether the given stream is currently selected.

Syntax

MediaPlayer.GetStreamSelected( StreamNum )

Parameters

StreamNum

A Long value specifying a stream ID number.

See Also

GetStreamGroup, GetStreamName


IsSoundCardEnabled

IsSoundCardEnabled Method

Returns a Boolean value indicating whether the computer's sound card is enabled.

Syntax

MediaPlayer.IsSoundCardEnabled

Return Values

This method returns the following values:

Value | Description
True | Sound card is enabled.
False | No sound cards are enabled.

Remarks

The IsSoundCardEnabled method determines whether the computer has one or more sound cards enabled.


Next

Next Method

Jumps to the next clip in the playlist.

Syntax

MediaPlayer.Next

Parameters

This method has no parameters.

See Also

Previous


Open

Open Method

Asynchronously opens the title specified by a String value.

Syntax

MediaPlayer.Open( TitleName )

Parameters

TitleName

Name of the title to open, including its protocol, path or HTTP URL.

Remarks

This method performs the same function as setting the FileName property, however, the Open method works asynchronously, allowing the calling application to continue performing tasks while the title is being opened. The Cancel method can be used to abort the Open method before the file is completely loaded.

See Also

FileName, Cancel


Pause

Pause Method

Suspends title playback at the current position.

Syntax

MediaPlayer.Pause

Parameters

This method has no parameters.

Return Value

This method does not return a value.

Remarks

This method performs the same action as clicking the Pause button on the playbar.

If SendPlayStateChangeEvents is set to True, this command causes a PlayStateChange event to occur, if the file is playing.

When a file is paused, the client control does not give up any system resources, such as the audio device.

See Also

FastForward, FastReverse, Play, Stop,


Play

Play Method

Starts playing a title from the starting position or continues playing a paused title.

Syntax

MediaPlayer.Play

Parameters

This method has no parameters.

Remarks

If SendPlayStateChangeEvents is set to True, this command causes a PlayStateChange event to occur, if the file is not already playing.

See Also

FastForward, FastReverse, Pause, Stop


Previous

Previous Method

Jumps to the previous item in the playlist.

Syntax

MediaPlayer.Previous

Parameters

This method has no parameters.

See Also

Next


Stop

Stop Method

Stops title playback.

Syntax

MediaPlayer.Stop

Parameters

This method has no parameters.

Return Value

This method does not return a value.

Remarks

If SendPlayStateChangeEvents is set to True, this command causes a PlayStateChange event to occur, if the file is not already stopped.

Calling this method does not change the current position, unless the file is not seekable. Non-seekable files are reset to position 0 when Stop is called. In addition, pressing the Stop button on the Player application resets the current position to zero.

This method causes the Media Player control to release any system resources it is using, such as the audio device.

To halt a play operation without changing the current position, use the Pause method.

See Also

FastForward, FastReverse, Pause, Play


StreamSelect

StreamSelect Method

Selects the given media stream.

Syntax

MediaPlayer.StreamSelect( StreamNum )

Parameters

StreamNum

A Long value indicating a stream number to select.

See Also

StreamCount property


Player Control Events

The control supports the following events.

Event | Description
Buffering | Occurs when the control begins or ends buffering.
Click | Occurs when a user clicks the mouse with the cursor in the image window.
DblClick | Occurs when a user double clicks the mouse with the cursor in the image window.
Disconnect | Occurs when the control is disconnected from the server.
DisplayModeChange | Occurs when the DisplayMode property changes.
EndOfStream | Occurs when the end of the title is reached.
Error | Occurs when the control has an error condition.
KeyDown | Occurs when a key is pressed.
KeyPress | Occurs when a key is pressed and released.
KeyUp | Occurs when a key is released.
MarkerHit | Occurs when a marker is reached.
MouseDown | Occurs when a mouse button is pressed.
MouseMove | Occurs when the mouse pointer is moved.
MouseUp | Occurs when a mouse button is released.
NewStream | Occurs when a new stream is started in a station.
OpenStateChange | Occurs when the control changes its open state.
PlayStateChange | Occurs when the control changes its play state.
PositionChange | Occurs when the current media position moves to a new position.
ReadyStateChange | Occurs when the control's state of readiness changes.
ScriptCommand | Occurs when a synchronized command or URL is received.
Warning | Occurs when the control encounters a possible problem.


Buffering

Buffering Event

Occurs when the control begins or ends buffering.

Syntax

MediaPlayer_Buffering( Start )

Parameters

Start

A Boolean value specifying whether data buffering has started or finished. True indicates that the data buffering has started.

Remarks

Buffering is called anytime data begins or finishes buffering. Buffering can occur at any time, and is influenced by factors such as network congestion.

Data buffering can be initiated by the properties of an .asf file (in how its images are stored, for example). Buffering is initiated anytime .asf file playback is stopped by pressing the Stop button or by calling the Stop method, and then is restarted (by pressing the Play button or calling the Play method). However, due to other factors such as network congestion, data buffering can occur almost anytime during playing of an .asf file.

Example

The following example displays a "buffering..." message when data buffering occurs:

Sub MediaPlayer_Buffering(Start)
  If Start = True Then      'Did buffering just begin?
    TextBox.Text = "Buffering..."
  Else   'Buffering done, clear text box
    TextBox.Text = ""
  End If
End Sub

See Also

BufferingCount


Click

Click Event

Occurs when a user clicks the mouse with the cursor in the image window.

Syntax

MediaPlayer_Click( Button, ShiftState, x, y )

Parameters

Button

An Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

ShiftState

An Integer value specifying a bit field with the least significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2 ). These bits correspond to the values 1, 2, and 4, respectively. The shift argument indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

x

A Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

y

A Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event is called only if SendMouseClickEvents is True.

See Also

DblClick, MouseDown, MouseUp, SendMouseClickEvents


DblClick

DblClick Event

Occurs when a user double clicks the mouse with the cursor in the image window.

Syntax

MediaPlayer_DblClick( Button, ShiftState, x, y )

Parameters

Button

An Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

ShiftState

An Integer value specifying a bit field with the least significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. The shift argument indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

x

A Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

y

A Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event is called only if SendMouseClickEvents is True.

See Also

Click, MouseDown, MouseUp, SendMouseClickEvents


DisplayModeChange

DisplayModeChange Event

Indicates changes to the DisplayMode property, such as from full-screen to half.

Syntax

MediaPlayer_DisplayModeChange

Remarks

The DisplayModeChange event is raised when the DisplayMode property changes. The current display mode appears in the DisplayMode property. State flags are listed under DisplayMode property.


Disconnect

Disconnect Event

Occurs when the control is disconnected from the server.

Syntax

MediaPlayer_Disconnect( Result )

Parameters

Result

A Long value specifying the cause of the disconnection.

Remarks

A disconnection can be caused by a network problem, a problem with the server, or other factors.


EndOfStream

EndOfStream Event

Occurs when the end of the title is reached.

Syntax

MediaPlayer_EndOfStream( Result )

Parameters

Result

A Long value specifying the status of the title after it has finished playing.

Remarks

A return value of zero indicates the title completed successfully.


Error

Error Event

Occurs when the control has an error condition.

Syntax

MediaPlayer_Error

Remarks

Use this event to trap errors. The Error event is sent when the Media Player control reports an error during playback. To process the error in your script, use the Visual Basic Err object or the properties listed in the See Also section.

See Also

ErrorCode, ErrorCorrection, ErrorDescription


KeyDown

KeyDown Event

Occurs when a key is pressed.

Syntax

MediaPlayer_KeyDown( KeyCode, ShiftState )

Parameters

KeyCode

An Integer value specifying a key code, such as vbKeyF1 (the f1 key) or vbKeyHome (the home key). To specify key codes, see the Visual Basic documentation.

ShiftState

A Integer value specifying a bit field with the least significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2 ). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

Remarks

This event is called when the control has focus and a key is pressed.

This event is called only if SendKeyboardEvents is True.

See Also

KeyUp, KeyPress, SendKeyboardEvents


KeyPress

KeyPress Event

Occurs when a key is pressed and released.

Syntax

MediaPlayer_KeyPress( KeyAscii )

Parameters

KeyAscii

An Integer value specifying a standard numeric ANSI keycode.

Remarks

This event is called when the Player control has focus and a key is pressed.

This event is called only if SendKeyboardEvents is True.

See Also

KeyDown, KeyUp, SendKeyboardEvents


KeyUp

KeyUp Event

Occurs when a key is released.

Syntax

MediaPlayer_KeyUp( KeyCode, ShiftState )

Parameters

KeyCode

An Integer value specifying a key code, such as vbKeyF1 (the f1 key) or vbKeyHome (the home key). To specify key codes, see the Visual Basic documentation.

ShiftState

A Integer value specifying a bit field with the least significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2 ). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

Remarks

This event is called when the control has focus and a key is pressed.

This event is called only if SendKeyboardEvents is True.

See Also

KeyDown, KeyPress, SendKeyboardEvents


MarkerHit

MarkerHit Event

Occurs when a marker is reached.

Syntax

MediaPlayer_MarkerHit( MarkerNum )

Parameters

MarkerNum

A Long value specifying the number of the marker that was reached.

Remarks

This event does not get called if the file is being scanned (fast forwarded or fast reversed)


MouseDown

MouseDown Event

Occurs when a mouse button is pressed.

Syntax

MediaPlayer_MouseDown( Button, ShiftState, x, y )

Parameters

Button

An Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

ShiftState

An Integer value specifying a bit field with the least significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2 ). These bits correspond to the values 1, 2, and 4, respectively. The shift argument indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

x

A Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

y

A Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event is called only if SendMouseClickEvents is True.

See Also

MouseUp, Click, DblClick, SendMouseClickEvents


MouseMove

MouseMove Event

Occurs when the mouse pointer is moved.

Syntax

MediaPlayer_MouseMove( Button, ShiftState, x, y )

Parameters

Button

An Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

ShiftState

An Integer value specifying a bit field with the least significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2 ). These bits correspond to the values 1, 2, and 4, respectively. The shift argument indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

x

A Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

y

A Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event is called only if SendMouseClickEvents is True.

See Also

SendMouseMoveEvents


MouseUp

MouseUp Event

Occurs when a mouse button is released.

Syntax

MediaPlayer_MouseUp( Button, ShiftState, x, y )

Parameters

Button

An Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

ShiftState

An Integer value specifying a bit field with the least significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2 ). These bits correspond to the values 1, 2, and 4, respectively. The shift argument indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

x

A Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

y

A Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event is called only if SendMouseClickEvents is True.

See Also

MouseDown, Click, DblClick, SendMouseClickEvents


NewStream

NewStream Event

Occurs when a new stream is started.

Syntax

MediaPlayer_NewStream


OpenStateChange

OpenStateChange Event

Occurs when the control changes its open state.

Syntax

MediaPlayer_OpenStateChange( OldState, NewState )

Parameters

OldState

A Long value specifying the previous OpenState property value.

NewState

A Long value indicating the new OpenState property value.

Remarks

Use this event to process changes in the OpenState property.

See Also

OpenState, SendOpenStateChangeEvents


PlayStateChange

PlayStateChange Event

Occurs when the control changes its play state.

Syntax

MediaPlayer_PlayStateChange( OldState, NewState )

Parameters

OldState

A Long value specifying the previous PlayState property value.

NewState

A Long value specifying the new PlayState property value.

Remarks

Use this event to process changes in the PlayState property.

See Also

PlayState, SendPlayStateChangeEvents


PositionChange

PositionChange Event

Indicates changes to the current media position, such as when the user selects (or seeks to) a new media position.

Syntax

MediaPlayer_PositionChange( oldPosition, newPosition )

Parameters

oldPosition

Double value indicating the position before it changed, in seconds.

newPosition

Double value indicating the current position, in seconds, after the position change occurred.

Remarks

Changes made directly to the CurrentPosition property do not trigger this event.


ReadyStateChange

ReadyStateChange Event

Indicates changes to the control's state of readiness.

Syntax

MediaPlayer_ReadyStateChange( ReadyState )

Parameters

ReadyState

Long value indicating the current state of readiness, after the change occurred.

Remarks

When you change the FileName property, applications should check the control's state of readiness before attempting to call the Play method on the newly opened file. Applications should call the Play method only if the ReadyState parameter equals mpReadyStateInteractive or mpReadyStateComplete.

Settings

Following are possible settings for the ReadyState parameter.

Setting | Value | Description
mpReadyStateUninitialized | 1 | The FileName property has not been initialized.
mpReadyStateLoading | 0 | The ActiveMovie control is asynchronously loading a file.
mpReadyStateInteractive | 3 | The control loaded a file, and downloaded enough data to play the file, but has not yet received all data.
mpReadyStateComplete | 4 | All data has been downloaded.


ScriptCommand

ScriptCommand Event

Occurs when a synchronized command or URL is received.

Syntax

MediaPlayer_ScriptCommand( scType, Param )

Parameters

scType

A String value specifying the type of script command.

Param

A String value specifying the value of the script command.

Remarks

Commands can be embedded among the sounds and images of an .asf file. The commands are a pair of Unicode strings associated with a designated time in the stream. When the stream reaches the time associated with the command the Media Player control sends a ScriptCommand event with two parameters, one parameter specifying the type of command being sent and one parameter specifying the command. The type parameter is used to determine how the command parameter will be processed. Any type of command can be embedded in an ASF stream to be handled by the ScriptCommand event.

One type of command is a URL (Uniform Resource Locator). URL-type commands received by the Player control are invoked automatically in your default Internet browser if the InvokeURLs property is True.

The Player control always processes incoming URL-type commands in the following manner:

  1. A URL-type command is received.

  2. ScriptCommand is called.

  3. After ScriptCommand returns, InvokeURLs is checked.

  4. If InvokeURLs is True and the command is a URL-type, the specified URL is invoked. If InvokeURLs is False or if the command is not a URL-type, the command is ignored.

When authoring an .asf file, you can specify which frame the new URL is displayed in by concatenating two ampersands and the name of the frame in the parameter field. The example below illustrates typical ScriptCommand parameters. It specifies that the URL mypage should be launched in the myframe frame.

Type = "URL"
Param = http://myweb/mypage.html&&myframe

The only other type of script commands automatically processed by the Player control at this time are FILENAME-type commands. When the Player control receives a command with a FILENAME type, it resets the FileName parameter, attempts to open the file named, and begins playing the new stream immediately.

You can embed any other type of command as long as you provide reciprocal code to handle the command. Though unknown commands are ignored by the Player control, they are still handed off to the ScriptCommand event.

This event does not get called if the file is being scanned (fast forwarded or fast reversed).

The following example checks first to see whether the received command is a URL. If it's not, it displays the command in a text box. This example could be used to display text captions embedded in an .asf file. With a small amount of modification, you could check for commands of type "CAPTION" and then author .asf files by using the "CAPTION" tag wherever you wanted to insert captions. You could also send VBScript commands through an .asf file and then build ActiveX HTML pages on the fly.

Example

The example code shows the ScriptCommand event procedure.

Sub MediaPlayer_ScriptCommand(Type, Param)
  If Not (Type = "URL") Then      'Not URL?
    TextBox.Text = Type + ": " + Param   'Show command
  End If
End Sub


Warning

Warning Event

Occurs when the control encounters a possible problem.

Syntax

MediaPlayer_Warning( WarningType, Param, Description )

Parameters

WarningType

A Long value specifying the type of problem encountered. The WarningType parameter can be one of the following values:

Constant | Value | Description
nsNoAudioDevice | 0 | The audio playback device is already in use.
nsUnknownStreamFormat | 1 | An unknown stream format was received.
nsPlaylistItemFailure | 2 | A file specified in the playlist could not be played.

Param

A Long value specifying additional information about the warning. This parameter specifies different information for different types of warnings. The following table describes the type of data in this parameter for each warning type:

Warning Type | Param information
nsNoAudioDevice | Always zero.
nsUnknownStreamFormat | The stream number of the invalid stream.
nsPlaylistItemFailure | The number of the clip in the playlist that failed to play.

Description

A String value specifying the description of the problem encountered.

See Also

SendWarningEvents


Player Control Objects

The control supports the following objects.

Object | Description
ActiveMovie | Returns an Active Movie player object, to provide support for backwards compatibility.
NSPlay | Returns an NetShow Player object, to provide support for backwards compatibility.


ActiveMovie Object

Provides access to ActiveMovie specific properties, methods, and events specific to previous versions of the Active Movie control. This is provided for backwards compatibility purposes only.

Syntax

MediaPlayer.ActiveMovie

Remarks

This is provided for backward compatibility purposes only.

See Also

NSPlay, Player Control Objects


NSPlay Object

Provides access to the NetShow Player properties, methods, and events specific to previous versions of the NetShow Player control. This is provided for backward compatibility purposes only.

Syntax

MediaPlayer.NSPlay

Remarks

This is provided for backward compatibility purposes only.

See Also

ActiveMovie, Player Control Objects


NetShow Netscape Plug-in

Netscape Player Plug-in

The Media Player includes a plug-in for Netscape Navigator that enables embedded playback of ASF, VOD, and RV/RA content in Navigator versions 3.02 and 4.04. The Netscape Player plug-in is fully scriptable and therefore supports most of the major functionality and capabilities of the Media Player ActiveX control.

Using the plug-in you can develop embedded applications in Navigator that:

  • Call the Player control’s methods to do things like controlling starting and stopping of the player,

  • Set and read the Player control’s properties to obtain status and change display and content information, etc.

  • Receive events from the Player control to dynamically handle script commands embedded in the ASF stream and to handle errors and custom commands.

The plug-in (npnsplay.dll) is installed automatically by the Player setup program. The plug-in has Live Connect enabled to support getting and changing properties and methods. Java classes and a JAVA peer Applet are also installed that send events to Java script in Netscape.

The plug-in also supports the following attributes for specifying the size of the control and the source file.

Attribute | Description
SRC | Analogous to the FileName Property. If this attribute is not specified, the player will be displayed at a quarter of the size specified by the Height attribute.
Width | Analogous to WIDTH parameter of the Object tag.
Height | Analogous to HEIGHT parameter of the Object tag.

Important:

  • Setting of all three of these attributes is required in order for proper functionality of the plug-in.

  • It is recommended that the parameter -start_java be inserted at the end of the shortcut into Netscape. This loads the Java VM first, which is the preferred method.

HTML Plug-In Example

The following HTML example demonstrates how to add the Player control to a Web page so that it can be interpreted by any browser. For more sample HTML on how to use the Netscape Player plug-in to use methods, properties, and events, please see the \Plugin directory in SDK\Samples\Client of the SDK.

The sample below is for simple embedding cases where processing events from the Player control (such as script commands) is not a requirement. This source also works correctly for Internet Explorer in addition to Netscape Navigator.

<!-- GENERIC ALL BROWSER FRIENDLY HTML FOR PLAYER V3 -->
<OBJECT ID="NSPlay" WIDTH=160 HEIGHT=128
 classid="CLSID:2179C5D3-EBFF-11CF-B6FD-0AA00B4E220"
 codebase="http://www.microsoft.com/netshow/download/en/nsdsinf.cab
 #Version=5,1,51,115"
standby="Loading Player components..."
type="application/x-oleobject">
<PARAM NAME="FileName" VALUE="http://Server/Sample.asf">
<Embed type="video/x-ms-asf-plugin"
 pluginspage="http://www.microsoft.com/netshow/download/player.htm"
          filename=" http://Server/Sample.asf"
          src=" http://Server/Sample.asf"
          Name=NSPlay
          width=290
          height=250
>
 </embed>
</OBJECT>
<br>
<a href="http://Server/Sample.asf">Start the media presentation in the stand-alone player.</a>

The sample below is for embedding and processing events from the Player control (such as script commands). This source also works correctly for Internet Explorer in addition to Netscape Navigator.

<!-- GENERIC ALL BROWSER FRIENDLY HTML FOR PLAYER V3 -->
<OBJECT ID="NSPlay" WIDTH=160 HEIGHT=128
 classid="CLSID:2179C5D3-EBFF-11CF-B6FD-0AA00B4E220"
 codebase="http://www.microsoft.com/netshow/download/en/nsdsinf.cab
 #Version=5,1,51,115"
standby="Loading Media Player components..."
type="application/x-oleobject">
<PARAM NAME="FileName" VALUE="http://Server/Sample.asf">
<Embed type="video/x-ms-asf-plugin"
 pluginspage="http://www.microsoft.com/netshow/download/player.htm"
          filename="http://Server/Sample.asf"
          src="http://Sample.asf"
          Name=NSPlay
          width=290
          height=250
>
</embed>
<!-- You only need to include the APPLET tag if you want to be able to handle script events.  Otherwise, you can remove it for a cleaner page look.  Do not set height and width less than 5; The browser will not render the page properly if you do.-->
<Applet MAYSCRIPT Code="NPDS.npDSEvtObsProxy.class" Width=5 Height=5 Name="appObs" >
</Applet>
</OBJECT>
<br>
<a href="http://Server/Sample.Asf">Start the media presentation in the stand-alone player.</a>

For additional information about the Netscape Player Plug-in please see the release notes.

The Netscape Player plug-in was developed for Microsoft by Digital Renaissance, Inc. To learn more about Digital Renaissance and its T.A.G. line of products, visit their Web site at http://www.digital-ren.com.


Player Control Samples

Sample | Description
Simple VB Script Sample | This sample demonstrates embedding and control of the player in a simple HTML page. Compare the VB Script in this sample with the next sample, which accomplishes the same this using JScript.
Simple JScript Sample | This sample demonstrates embedding and control of the player in a simple HTML page. Compare the JScript in this sample with the previous sample, which accomplishes the same this using VB Script.
Fnhanced Player Sample | This sample builds on the concepts demonstrated in the simple sample. It uses text boxes to display some of the title properties. It also captures state change events and uses them to display the state of the control. A "timer" object is incorporated to update text boxes with packet status information every two seconds.
SAMI Sample | This sample demonstrates using a Synchronized Accessible Media Interchange file to provide closed captioning to a multimedia presentation.


ASX Metafile Reference

© 1996-1998 Microsoft Corporation. All rights reserved.


NetShow ASX Metafiles

Advanced Streaming redirector files, also called ASX metafiles are text files which, in their simplest form, contain information about the Uniform Resource Locator (URL) for a piece of media content. This information is processed by the client, Microsoft® Media Player, which then opens the media defined in the ASX file.

The most common use of ASX files is using a hyperlink in a Web page to an ASX file that directs the client to the streaming server. Most Web browsers do not recognize the protocols used for streaming media (MMS, NSM, PNM), which means you cannot use hyperlinks in HTML directly to a media streaming server. To work around this problem, you can create ASX files that contain the information needed by the player to connect to streaming media servers, and store them on a Web server. Once the files are stored on a Web server, you can use hyperlinks in a Web document to the stored ASX files. When a file with a filename extension of .asx is opened, control is transferred to Media Player which then processes the file and plays the media defined in it.

You also can use the more sophisticated features of ASX files to deliver, among other things, branding information, advertisements, and playlists to users receiving your content. ASX files enhance the integration of Microsoft® NetShow™ with Web commerce applications, such as Microsoft® Site Server version 3.0, by allowing for the personalization and customization of content delivery. Using ASX metafiles, you can insert advertisements into the display area of the player, as well as graphics that direct the user to your Web site. You can even use Active Server Pages (ASP, or .asp files) to generate ASX files that link to your content. ASX metafiles allow the content creator greater control over how content is delivered to the user.

This section contains information about the following ASX metafile topics:

  • Understanding ASX Files
  • Working with ASX Files
  • Creating a Basic ASX File
  • Understanding ASX Elements
  • Using ASX Elements
  • Using ASP to Dynamically Generate ASX Files


Understanding ASX Metafiles

An ASX file provides information that Microsoft® Media Player uses, such as the Uniform Resource Locator (URL), to receive either unicast or multicast streams from an intranet or the Internet. You also can use ASX files to deliver the path to a stored media file on a network drive, but this can be accomplished through other means as well, and is not covered here. Both Microsoft® NetShow™ and RealNetworks® RealAudio® metafiles can be opened by Media Player. These files are loaded quickly by the client, and contain information for the following purposes:

  • To transfer control from the Hypertext Transfer Protocol (HTTP) browser to the player control, so that streams can be directed to the player. If you do not have Microsoft® Internet Explorer, you cannot define hyperlinks in a Web page using the MMS (Microsoft Media Server) protocol because the MMS protocol is not recognized. You can link to an ASX file on a Web server that then points the client to the NetShow server via the MMS protocol.
  • To represent an announcement of information necessary to access a program on a NetShow station.
  • To provide references to multiple pieces of content and rules for protocol rollover that the client uses to process them.
  • To provide a playlist that defines the order in which pieces of content are streamed to the player.


Working with ASX Files

An ASX file can be sent in e-mail, used as a link reference on a Web page, created dynamically using Active Server Pages (ASP), or exist as a stand-alone file on a hard disk drive. An ASX file, in its simplest form, is a link to an Active Streaming Format (ASF or .asf) file or stream. When a user opens an ASX file, Microsoft® Media Player is started. The player then attempts to open the file or stream defined in the ASX file. An ASX file also can be used to provide the user with a link to another ASX file, to an Active Server Page, or to a NetShow station (NSC) file. An NSC file is used to define real-time content, or NetShow stations to Media Player.


Important

When an ASX file is opened by the player, the entire file is parsed and all URLs resolved before any content is played. If referenced content includes associated graphics, all graphic files referenced are downloaded before the content is played. This prevents long pauses between pieces of content while a graphic is being downloaded, but also can cause a long delay before the first piece of content is played.

For more information on creating NSC files, see NetShow Server in the NetShow Documentation installed with NetShow Server.


Creating a Basic ASX File

An ASX file must have a minimal set of information in order to function successfully. A basic ASX file can be used to connect a user to a piece of content from a link on a Web page, or by attaching it to an e-mail message. In order for the user to connect, the ASX file must contain a Uniform Resource Locator (URL) for a piece of content. The structure of the ASX file also must follow Extensible Markup Language (XML) standards. Simple ASX files can be created using any text editor, such as Microsoft® Notepad. ASX files must have a file name extension of .asx.


Important

An ASX file must not include any formatting codes from a word processor, such as Microsoft® Word. To make sure no formatting codes are included in the ASX file, save the file as a plain text or ASCII file.


Example of a Basic ASX File Using an Entry Element
<ASX version = "3.0">
   <Entry>
      <Ref href = "mms://nsserver/content/sample.asf" />
   </entry>
</ASX>


Example of a Basic ASX file Using an EntryRef Element
<ASX version = "3.0">
   <EntryRef href = "http://nsserver/on-demand/myfile.asx" />
</ASX>


Adding Comments in an ASX File

You can add comments to ASX files following Extensible Markup Language (XML) syntax. Comments can appear anywhere except within element content (between element open and close tags). They are not part of the document's character data, and are ignored when the ASX file is parsed.


Syntax

<!-- . . . ->


Example
<!-- This is an example comment in XML syntax. This info is only visible when editing an .asx file. -->


Using Relative Links In ASX Files

Relative links are a fully supported feature of Microsoft® NetShow™ ASX metafiles. You can use relative links in ASX files similar to how you use them in Hypertext Markup Language (HTML) documents. The use of relative links allows you to create ASX files which are portable, meaning you can copy or move an entire directory structure to another server without updating the paths to graphic files used as Logos or Banners or the Href attributes of MoreInfo elements (if on the same Web server as the stored ASX file). It is important to remember that relative links, in any application that supports them, work because the parts of the Uniform Resource Locator (URL) you do not include in the Href attribute of an element do get included in the URL sent by the application to the server when the URL is requested. This means that the protocol (such as Hypertext Transfer Protocol [HTTP]), the server name, and the virtual directory the file containing the relative link is located in are included in the URL sent to the server. If the file, media, or URL you link to using a relative link do not reside on the same server as the ASX file the relative link is not valid.

You can use relative links in an ASX file by creating a simple ASX file in version 1.0 ASX syntax which contains a link to another ASX file in 3.0 syntax. All metadata (Title, Author, Copyright etc.) displayed in the player is read from the second ASX file. You can use links (values of Href attributes) in the second ASX file which are relative to that ASX file (meaning the location from where the file was opened), similar to using relative links in a Web page. All relative links in the version 3.0 ASX file must be fully relative rather than drive relative, meaning that you cannot use a relative link that begins with a "\" character. When an URL begins with a "\" character the link is drive relative, which causes the player to attempt to open the file linked to on the drive the ASX file was opened from. Because Web servers use virtual directories, the player tries to find the file in a subdirectory of a virtual directory. Even if the path happened to be valid, a user would not have rights to access the physical directory on that Web server.

You can use drive relative links when using ASX files on a single computer where all files linked to in the ASX file exist on a storage device in that computer. However, you cannot stream media in this manner.


Important

When you use a link to another ASX to allow for relative links, the name displayed in the Title bar of the player is the name of the original ASX file (the one in version 1.0 syntax).


Important

Relative links cannot be used for URLs to a NetShow server because a different protocol (MMS) is used for accessing NetShow content. You can use relative links to NetShow content if you are if the content is streamed via HTTP, provided you are not using port 80 for both your Web server and your NetShow server.


An example of a version 1.0 ASX file pointing to a version 3.0 ASX file that contains relative links
ASF http://mywebserver/metafiles/relativelink.asx


An example version 3.0 ASX file containing relative links
<ASX version = "3.0">
   <Banner href = "graphics/logo1.jpg">
   <MoreInfo href = "category1/category1.htm" />
   </Banner>
   <Entry>
      <Ref href = "mms://NSserver/myfile.asf" />
   </Entry>
</ASX>

In these examples, the first ASX file, the file in version 1.0 syntax, can exist anywhere accessible to the user. There must be a link on a Web page that points to this ASX file so the user can click on it. The version 3.0 ASX file must exist in the metafiles virtual directory on the Web server named mywebserver. The file logo1.jpg must be in a subdirectory named graphics of the physical directory which is defined as the metafiles virtual directory. The Web document category1.htm must reside in a subdirectory to the metafiles directory named category1.


Important

This information on relative links is true only when using a link to an ASX file that is opened in the stand-alone player. When you use the embedded Microsoft® Media Player ActiveX™ control, all links are relative to the page on which the control is hosted.


Using ASP to Dynamically Create ASX Files

You can use Active Server Pages (ASP) to dynamically generate ASX files based on user information.


Important

When you use ASP to generate ASX files you must define a Response type variable as well as a Response expire variable in the ASP file due to latency issues with the client.

All header information must be contained on the first line of the ASP string returned to the client.


An example ASP used t generate an ASX file.

An example ASP used to generate an ASX file.
<%Response.ContentType = "video/x-ms-asf"%><%Response.expires=0 %><ASX VERSION="3.0">
   <Title></Title>
   <Entry>
      <Ref href ="mms://streamer.microsoft.com/hindenburg.asf" />
      <Title><%= Time%></Title>
   </Entry>
</ASX>


Understanding ASX Elements

ASX Files are based on the Extensible Markup Language (XML) syntax, and are made up of various elements with their associated tags and attributes. Each element in an ASX file defines a particular setting or action to the client. Some elements must be located in a specific position in the file relative to other elements. Some elements have required tags and attributes that must be defined in the ASX file. Element names and attributes are not case-sensitive.


Using ASX Elements

The most important part of successfully using ASX files is the correct syntax of the ASX elements. Syntax errors in an ASX file can cause anything from a single attribute being overlooked, to the ASX file not being recognized as valid and failing to work at all. Almost as important is the order in which the elements appear in the ASX file. The attributes of some elements override the attributes of similar elements in different sections of the ASX file. Following is a list of all ASX elements that link to the sections about them. Each section contains a definition of the element, its attributes and their values, and special conditions related to the element:

  • Abstract
  • ASX
  • Author
  • Banner
  • Base
  • Copyright
  • Duration
  • EndMarker
  • Entry
  • EntryRef
  • Event
  • Logo
  • MoreInfo
  • Preview/Duration
  • Ref
  • StartMarker
  • StartTime
  • Title


Abstract

The Abstract element contains text that represents a description of the associated ASX, Banner or Entry element. This text is displayed by the player in both the Display panel and the Properties dialog box.

If the Abstract element is used in an ASX element, the text is displayed as a ToolTip when the mouse is placed over the title of the show in the Show bar. The title displayed in the Show bar comes from the Title element in an ASX element. The text in the Abstract element also is displayed under Description on the Show tab of the Properties dialog box.

When you use the Abstract element inside an Entry element in the ASX file, the text is displayed as a ToolTip when the mouse is placed over the clip title in the Display panel, and under Description on the Clip tab of the Properties dialog box.

The Abstract element contains the text displayed as a ToolTip for a Banner graphic when it is used as a child element to the Banner element.


Syntax

<abstract>

text string

</abstract>


Important

If there is more than one Abstract element defined within the scope of another element (the parent element), meaning that more than one Abstract tag is used between the opening tag and the closing tag for another element, only the first Abstract element is used. All other Abstract elements in that scope are ignored. An example of this is:

<Entry>
   <Ref href = "mms://nsserver/pubpt/title1.asf" />
   <Abstract>Text displayed as a tooltip</abstract>
   <Abstract>Click here to go to our site</abstract>
</entry>

Only the first Abstract element is used, which results in the description for this Entry element (the clip) displaying "Text displayed as a tooltip." The second Abstract is not displayed anywhere.


Attributes

None


Number of Occurrences per Parent

None or one


Parent Elements

ASX

Entry

MoreInfo


Child Elements

None


Example
<ASX version = "3.0">
   <abstract>
   This text will show up as a ToolTip
   </abstract>
   <Title>Hover over this title for a ToolTip.</title>
</ASX>


ASX

The ASX element defines a file as an ASX file. The first four characters of an ASX file must be <asx. Other elements, such as Title and Author, defined within the scope of the ASX element (where ASX is the parent element), are associated with the Show information displayed by Microsoft® Media Player.


Syntax

<asx

version = “#”

previewmode = “yes” | “no”

BannerBar = “AUTO” | “FIXED”

>

. . .

</asx>


Attributes

Version (this is a required attribute)

The value of the version attribute is the a decimal indicating the version number of the syntax for the ASX file. For Microsoft® Media Player version 3.0, the syntax version number is 3.0. Microsoft® Media Player 5.2 supports all previous versions of ASX syntax. Acceptable values for the Version decimal include: “3.0,” and “3” with no decimal point.

PreviewMode

If the value for the PreviewMode attribute is “yes,” the player immediately enters Preview Mode when a title is opened. When the player enters Preview Mode, each clip referenced in the ASX file is previewed in the player. The duration of the preview of the piece of content is determined by the PreviewDuration element. Possible values include “yes” and “no.”

The default value for this attribute is “no.”

BannerBar

The value of the BannerBar attribute defines whether or not the player reserves space for a Banner graphic. A Banner is a graphic that is displayed in the Video area of the player while content is playing. A Banner is added to the content by using the Banner element. If the value is “FIXED,” the player reserves a space 32 pixels high by 194 pixels wide for a Banner graphic in the Video area for every piece of content played. The space is reserved 6 pixels above the bottom edge of the Video area, allowing space for the 6-pixel border. The Banner is centered horizontally. If a piece of content does not have a Banner associated with it, the space reserved for one is black.

If the value for this attribute is “AUTO,” the client reserves space for the Banner bar only when a piece of content includes one.

The default value for this attribute is “AUTO.”


Important

If you create an ASX file with multiple clips (Entry or EntryRef elements) and set the value of the BannerBar attribute to “AUTO,” the player will resize for each piece of content, which it does when the size of the video media differes from clip to clip. This may not be a desired effect. If you want the size of the Microsoft Media Player window to stay the same (except when the video size changes) you can use the “FIXED” value for the BannerBar attribute.


Number of Occurrences per Parent

The ASX element has no parent elements. The ASX element must be the first element in any ASX file.


Parent Elements

None


Child Elements

Abstract

Author

Base

Copyright

Duration

Entry

EntryRef

Logo

MoreInfo

PreviewDuration

Repeat

Title


Example
<asx
   version = "3.0"
   previewmode = "yes"
>
   <EntryRef href = "http://server/content/program1.asf" />
</asx>


Author

The Author element is a text string representing the name of the author of the ASX file. You can use the Author element in the ASX and Entry elements. The text contained in the Author element is displayed in the Display panel and Properties dialog box of the player.

If the Author element is used in the ASX element, the text is displayed on the Show tab of the Properties dialog box.

You also can use the Author element in the Entry element, in which case the text is displayed under Clip Author in the Display area and on the Clip tab of the Properties dialog box.


Syntax

<author>

text string

</author>


Parent Elements

ASX

Entry


Example
<author>
L. Magnifico
</author>


Banner

A Banner element in an ASX file is used to define an URL to a graphic file that is displayed in the display area (the area where video content is rendered) of the player beneath the video content. If the media is audio only, the Banner graphic is displayed by itself. The player reserves a 32-pixel-high-by-194-pixel wide space (the BannerBar) for the graphic. If the graphic defined in the URL is smaller than the reserved 32*194 pixel space, it is displayed at its original size. If the graphic linked to is larger than the reserved space, the graphic fills the space below the video display.

You can use an Abstract element within the scope of the Banner element to display text as a tooltip when the user holds the mouse cursor over the Banner graphic. You also can use a MoreInfo element as a child element to Banner, which defines an URL the user is taken to (the URL can be any path or protocol, such as an email link, an HTTP URL to a Web site, or even a Javascript URL) when the Banner graphic is clicked on. When the mouse pointer is held over the graphic it becomes embossed, making it look like a button.


Syntax

<Banner>

Href = “URL”

</Banner>


Attributes

Href (this is a required attribute)

The value of the Href attribute is an URL to a graphic file that is displayed in the BannerBar of the player.


Child Elements

Abstract

MoreInfo


Example of a Banner element without child elements
<banner href = "http://www.servername.com/logos/banner1.bmp" />


Example of a Banner element with a child element
<banner href = "http://www.servername.com/logos/banner1.bmp">
<!-- This is a comment. The text in the Abstract element below is displayed as a Tooltip when the mouse is over the Banner graphic.
End comment. -->
   <Abstract>Click here to go to our Web site</abstract>
   <MoreInfo href = "http://www.servername.com" />
</Banner>


Base

The Base element defines a Uniform Resource Locator (URL) string appended to (the front of ) URL-flip URLs sent to the client. The Base element is similar to a home directory for relative links. The Base element affects only URLs sent to the client using script commands.

URL-flipping is a scripting mechanism you can use to cause the player to flip to a new URL when a script command is received. To learn more about using script commands, see Inserting Script Commands in Microsoft® NetShow™ Tools.


Syntax

<Base

href = “URL”

/>


Important
  • If the URL does not end with a ‘/’ character, one is appended (to the end) by the client.
  • If the Base element is defined as part of an ASX element, the definition becomes the default for the entire ASX file.
  • If the Base element is defined as part of an Entry element, the definition applies to that element only. A Base element in an Entry element overrides the definition of a Base element in an ASX element.


Attributes

Href (this is a required attribute)

The value of the Href attribute is the URL that is appended to URLs sent to the client.

The default value for the Href attribute is null.


Example
<Base href="http://www.servername.com/" />


Copyright

The Copyright element is a text string that specifies the copyright information for an ASX or Entry element. The copyright information is displayed in the Details area of the player and the Properties dialog box.

When used in the ASX element the copyright information is displayed only on the Show tab of the Properties dialog box. If you use the Copyright element in an Entry element, the text is displayed in the Clip bar of the Display area and on the Clip tab of the Properties dialog box.


Syntax

<Copyright>

text string

</Copyright>


Example
<Copyright>Copyright© 1998, CompanyName®</Copyright>


Duration

The Value attribute for the Duration element defines the length of time a stream is to be rendered by the client. It is possible to set the value of the Value attribute to a length of time that exceeds the end of the content stream, in which case the stream terminates normally.


Syntax

<Duration

value = “hh:mm:ss.fract”

/>


Attributes

Value (This is a required attribute)

The length of time, in hours, minutes, seconds and hundredths of seconds, that a stream is rendered by the player.

The default value for the Value attribute is the entire length of the content stream or media.


Parent Elements

Entry

Ref


Example
<Duration value = "00:00:30" />
<Duration value = "1:01.5" />      This is the same as 61.5 seconds.


EndMarker

The EndMarker element defines the named or numeric marker index where the player is to stop rendering the stream defined in the associated Entry or Ref element. An associated element is the Parent element of an element.


Syntax

<EndMarker

number = “#”

name = “marker name”

/>


Important
  • The EndMarker element can have a value for either the Number or Name attribute, but not both.
  • In Preview Mode, reaching an EndMarker stops the preview. This is true even if the PreviewDuration has not elapsed.
  • An EndMarker element takes precedence over a Duration element.
  • An EndMarker element defined within a Ref element, which is defined within an Entry element, will take precedence over an EndMarker element defined within that Entry element.
  • It is possible to define an EndMarker that specifies the end before the beginning. You can specify a marker for the content to stop rendering that is placed earlier in the content than a marker defined for the StartMarker element. In this case, no content plays. No error is generated.


Attributes

Number

The number of a numeric marker in the index.

The default value is the end of the content.

Name

The name of a named marker in the index.

The default value is the end of the content.


Example
<EndMarker number = "17" />
<EndMarker name = "MarkerH" />


Entry

The Entry element is the fundamental construct in an ASX file. The Entry element and its associated attributes define to the player meta-information for a single, logical piece of content. This single piece of logical content is called a clip. Elements which are defined within an Entry element are displayed by the player in the Clip information area in the Display panel, as well as the Clip tab in the Properties dialog box.


Syntax

<Entry

ClientSkip = “yes” | “no”

SkipIfRef = “yes” | “no”

>

. . .

</Entry>


Attributes

ClientSkip

If the value of the ClientSkip attribute is “no,” the player does not allow the user to skip the piece of content defined by the Entry element using the player controls.

The default value is “yes.”

SkipIfRef

The SkipIfRef attribute pertains only to Entry elements that are included through the use of an EntryRef element. The EntryRef element references another ASX file for logical inclusion in the current file. If the value of the SkipIfRef attribute for an Entry element is “yes,” the player ignores this pulled-in Entry, and moves on to the next Entry element, if any. The next Entry element can be the next Entry in the original file, or the next Entry in the ASX file referenced in the EntryRef element.

The default value is “no.”


Number of Occurrences per Parent

Zero or more


Parent Elements

ASX

Event

Repeat


Child Elements

Abstract

Author

Copyright

Duration

EndMarker

Logo

MoreInfo

PreviewDuration

Ref

StartMarker

StartTime

Title


Example
<ASX Version = "3.0"
   <Title>The Something Catchy Station on Our Site</Title>
   <MoreInfo href = "http://www.server.com" />
<Entry>
   <Title>Catchy Tunes</title>
   <Abstract>Tunes you can’t get out of your head</abstract>
   <Copyright>Copyright© 1997 Company Name®</copyright>
   <Ref href = "http://server/catchy.nsc" />
   <Ref href = "http://backup/catchy.nsc" />
</Entry>
</ASX>


EntryRef

The EntryRef element is used when the content of an Entry is defined in an external ASX file. The EntryRef element is only for linking to another ASX file. Using the EntryRef element is similar to including the textual contents of the referenced ASX file into the current position of the current ASX file.


Syntax

<EntryRef

href= “URL”

ClientBind = “yes” | “no”

>

. . .

</EntryRef>


Important
  • The referenced ASX file can contain one or more Entry elements.
  • Any EntryRef elements in the referenced ASX file is ignored. This means that ASX files can be nested one level only.
  • The Entry elements of the ASX referenced ASX file are included as Entry elements in the original ASX file. The Entry elements are then processed as any other Entry element. The parser keeps track of whether the contents of this Entry element originated with the current ASX file or the ASX file referenced in the EntryRef element in order to adhere to the SkipIfRef attribute of the Entry element.
  • The ASX element and its attributes in the included ASX file are ignored.
  • If a user bookmarks the piece of content defined in the included ASX file, or adds a Favorites entry to it, the URL used to define it is the URL to the ASX file in the EntryRef element. If the value of the ClientBind attribute is “no,” the user cannot bookmark this URL, or add it to the Favorites list.


Attributes

Href (This is a required attribute)

The value of the href attribute is a URL to a referenced ASX file.

ClientBind

The value of the ClientBind element either allows or inhibits the users ability to add the URL defined in the href attribute of the EntryRef element to the Media Player Favorites list. If the value is “no,” users cannot add this URL to the Favorites list in the player.

The default value is “yes.”


Example
<ASX Version = "3.0">
   <Title>Cool Midi Music</Title>
   <MoreInfo href = "http://www.server.com" />
<Entry>
   <Title>Midi Disco Lounge</title>
   <Abstract>Disco, the way it was meant to be!</abstract>
   <Copyright>Copyright© 1998 Company Name®</copyright>
   <EntryRef href = "http://server/disco.asx" ClientBind = "no" />
</Entry>
</ASX>


Event

An event is script command embedded in a stream sent to the client that consists of a double string. The first string is the word event (this is case-sensitive), and the second string is the event name. The event name in the second string must match the event name defined in the ASX file. The two are case-sensitive to each other. Events can be sent to a client receiving a real-time stream, or can be saved in a .asf file that gets delivered as an on-demand unicast stream. When the script command is received, the client processes the Event.

The Event element defines a scope of Entry and/or EntryRef elements that play whenever the script command including the named event is received by the player. This allows the author to specify a behavior for stream switching in near real-time, as opposed to pre-authored stream changes using references to other pieces of content or ASX files. The following example demonstrates using the Event element in an ASX file to deliver advertisements to the client without disconnecting the user from the content being viewed. The author also can define what action the client takes after playing the stream defined in the Event element.


Syntax

<Event

Name = “text string”

WhenDone = “RESUME” | “NEXT” | “BREAK”

Refresh = “yes” | “no”

>

. . .

</Event>


Important
  • If multiple Event elements within an ASX element have identical values for their Name attributes, the player uses the first occurrence within the ASX element, and ignores all others.
  • The order in which Event elements appear within an ASX element is not significant.
  • Events received by the client during the processing of another Event are discarded. Nesting events is not supported.
  • Event content is not constrained by the PreviewDuration element when in Preview Mode. This means that the full length of Event content can be played by the client even if the PreviewDuration for the active Entry element expires prior to the end of the Event.


Attributes

Name (This is a required attribute)

A text string representing the event defined in the ASX file by the Event element. The value of the Name attribute is matched against the contents of a script command embedded in the stream that contains a double-string. The value of the Name attribute is case-sensitive, and must match exactly the contents of the double-string in the script command.

WhenDone (This is a required attribute)

The value for this attribute defines what the player does after playing the referenced Event content.

RESUME

The player resumes playing the current Entry (the Entry or clip that is interrupted by the Event) at the same point where it stopped if the content is stored content, or at the current position of the content if the content is real-time, or live.

NEXT

The client plays the next Entry element as if the Event had not occurred and it had reached the end of the content.

BREAK

The BREAK value is used to end a Repeat loop as if the repeat count had been completed. This is the same as not setting the Count attribute of the Repeat element. If the current Entry is not within a Repeat element, then the BREAK value instructs the player to go to the end of a playlist as if the final Entry had been completed normally.

Refresh

If the value of the Refresh attribute is “yes,” the client automatically refreshes the Event URL defined in the href attribute after the Event has been rendered. This allows subsequent rendering to use new content and/or meta data for the event.

The default value for this attribute is “no.”


Number of Occurrences per Parent

Zero or More


Parent Elements

ASX


Child Elements

Entry

EntryRef


Example
<ASX version = "3.0" BannerBar = "FIXED">
   <Title>Music Selections on Our Site</Title>
   <Logo href = "http://server/logos/icon1.gif" style = "ICON" />
   <Logo href = "http://server/logos/mark1.jpg" style = "MARK" />
<MoreInfo href = "http://server/main" />

<!-- This is a comment section.
The following section defines a lead-in advertisement.
End comment section -->

<Entry ClientSkip = "no">
   <Ref href = "http://www.server/ads/leadin.asf" />
   <Banner = "http://server/logos/image2.gif">
   <MoreInfo href = "http://server/main" />
   <Abstract>Click here to find out about other cool stuff</Abstract>
   </Banner>
</Entry>

<!-- This is a comment section.
The section below defines the featured content.
End comment section -->

<Entry>
   <Title>Songs to Hum and Tap to</Title>
   <Copyright>Copyright Info</Copyright>
   <Logo href = "http://www.server/logos/icon2.gif" Style = "ICON" />
   <MoreInfo href = "http://server/humtap">
   </MoreInfo>
   <Ref href = "http://server/stations/humtap.nsc" />
   <Ref href = "http://backupserver/stations/humtap.nsc" />
</Entry>

<!-- This is a comment section.
The section below defines two dynamic advertisements with dynamic "meta" data, one regional and one local. When the playing of the ads is complete the featured content resumes.
End comment section -->

<Event Name = "Regional-Ad" WhenDone = "RESUME" Refresh = "yes">
   <EntryRef
      href = "regional.asp"
      ClientSkip = "no" />
</Event>
<Event Name = "Local-Ad" WhenDone = "RESUME" Refresh = "yes">
   <EntryRef
   href = "local.asp"
   ClientSkip = "no" />
   </Event>
</ASX>


Logo

The Logo element specifies the URL for a graphic file that is associated with an ASX or Entry element (a show or clip). These graphic files are displayed in the player as they are defined by the Logo element attributes. Logo elements defined within an ASX element (where the ASX element is the parent element) are displayed for the duration of a playlist. All graphic styles except “ICON” are displayed in the View area of the player. The “ICON” style images are displayed next to the title of the clip or show in the Display panel, depending on the parent of the Logo element. If no “ICON” style Logo elements are included in the ASX, the graphic displayed next to the title is the icon associated with the file name type.

Logo formats follow the Microsoft® Internet Explorer Channel guidelines as follows, with all sizes in pixels:

ICON - 16 height x 16 width

MARK - 32 height x 80 width

Media Player supports GIF, BMP, and JPG graphic formats.


Syntax

<Logo

href = “url”

Style = “ICON” | “MARK”

/>


Important
  • When the Logo element is used to include graphics with the content delivered to the client, it is important to remember that the size of the View area is adjusted automatically to allow space for the graphic. If using an ASX file to define a playlist, each clip in the playlist can cause the player to resize. This can be an undesirable effect. If the dimensions of a video clip differ from another clip in a playlist the player window is resized anyway.


Attributes

Href (This is a required attribute)

Specifies the URL to a graphic file associated with an ASX or Entry element. The graphic file is displayed in the client next to the information defined by the associated element.

Style (This is a required attribute)

Specifies how the graphic file logo is displayed by the player.

ICON

The graphic specified with the “ICON” style replaces the icon displayed on the Display panel next to the Show or Clip title.

If the value of the Style attribute is “ICON,” the graphic specified in the Href attribute is displayed next to the title of the show or clip. If the parent element of the Logo element is ASX, the Logo graphic is positioned to the left of the Show title in the Display panel. If the parent element is Entry, the Logo graphic is positioned to the left of the Clip title.

MARK

The “MARK” style is only valid if the parent element of the Logo element is ASX. The “MARK” style graphic is displayed in the lower right corner of the Video area (allowing for a six pixel border) while the player is connecting to a server and opening a piece of content. The “MARK” style graphic is not displayed once the title has started playing.

The default value for this attribute is “ICON.”


Number of Occurrences per Parent

If the Logo element is used in an ASX file, at least one Style must be defined because Style is a required attribute of the Logo element. Within a single Entry element, up to one instance of each Style, ICON or MARK can be defined. There can be no more than one instance of each type of Style in a single Entry element.


Example
<Logo href = "http://server/logos/image1.gif" Style = "ICON" />


MoreInfo

The MoreInfo element allows the content creator to provide a URL to a Web site, link to an email address, or specify a script command to execute. The URL, link, or script command can be accessed by opening the More Information sub-menu of the File menu in the player. This sub-menu contains three commands, Show, Clip, and Banner. One or more of these commands is available in the menu depending on the element(s) the MoreInfo element is associated with. If associated (within the scope of) an ASX element, the MoreInfo element is associated with the Show in the player. Using a MoreInfo element as a child element of an Entry element associates the MoreInfo element data with the clip in the player. If you use MoreInfo within the scope of a Banner tag, the Banner graphic, as well as the Banner command on the More Information sub-menu, can be clicked on. When it is clicked on, the URL or script command is executed. If the Href attribute of the MoreInfo element is an URL to a Web site, the browser starts and navigates to the URL. If it is an email link, the users email application starts. If the Href value is a script command, it is executed in the browser.

The URL defined in the Href attribute is displayed as a ToolTip when the mouse cursor is placed over the Banner graphic, if one is included. If there is an Abstract element within the scope of the MoreInfo element, the Abstract text is displayed as the ToolTip.


Syntax

<MoreInfo

href = “URL”

Target = “frame”

>

. . .

</MoreInfo>


Important
  • If a MoreInfo element is used in an ASX file, the mouse cursor changes to a pointing hand when placed over the title (of the clip if in an Entry element or of the Show if in an ASX element) or Banner graphic (if the MoreInfo element is a chile element to a Banner element). Also, the URL defined in the href attribute of the MoreInfo element is displayed in the Status bar so that users know to click in the area to go to the URL displayed.
  • It is recommended that you use a Target attribute if using MoreInfo elements with ASX files that link to content displayed as an embedded control in a Web page or another container. If you do not use a Target attribute, or set the value of the Target attribute to _self, the page containing the embedded control is replaced with the URL defined in the MoreInfo element.


Attributes

Href (This is a required attribute)

Specifies an URL to a Web site. This is the URL the user is linked to when the user clicks on the Banner graphic or selects an item in the More Information submenu of the File menu.

Target

The target attribute defines which browser frame or window the page defined in the Href attribute is opened in. The values for the Target attribute follow standard Hypertext Markup Language (HTML) syntax and definitions.

If the ASX file is opened in the stand-alone player, the Target attribute is ignored, and the URL is opened in a new browser window.

In the case of the embedded control, if there is no Target attribute defined the URL is loaded into the current browser window, and replaces the existing page. This means that if a user accesses a MoreInfo link by clicking the Banner graphic in the Video area, the content stops playing, and the URL defined in the Href attribute is rendered. It is recommended that you use a Target attribute for MoreInfo links in the embedded case.

The possible values for this attribute are the values for using the target argument in an HTML document as follows:

_blank - The document defined in the URL is loaded in a new browser window.

_self - The document defined in the URL is loaded in the same frame as the current document containing the control.

_parent - The document is loaded into the immediate parent frame of the current frame. This is the same as the current frame if there is no parent frame.

_top - The document referenced in the URL is loaded in the full browser window, replacing all other frames or documents.


Parent Elements

ASX

Entry

Banner


Example
<ASX version = "3.0">
<!-- This is a comment.
The MoreInfo tag below makes the Show title in the Display panel clickable. If the MoreInfo tag is under an Entry element, the title of the clip can be clicked on.
When a user places the mouse over the title, the URL defined in the href attribute is displayed in the Status bar. When a user clicks the title, the browser starts and navigates to the page defined in the URL. When the Banner is the parent element, the user can click the graphic in the Video area to open the URL defined in the MoreInfo element.
End comment. -->
   <MoreInfo href = "http://www.server.com/info" />
   <Entry>
      <Ref href = "mms://nsserver/content/title1.asf" />
   </Entry>
</ASX>


PreviewDuration

The PreviewDuration element defines the length of time the clip defined in the associated Entry or Ref element is played in Preview Mode. An associated element is the element parent element.


Syntax

<PreviewDuration

value = “hh:mm:ss.fract”

/>


Important
  • The default value for the Value attribute is inherited from the ASX element. If there is no PreviewDuration defined for the ASX element, the value inherited from the ASX element is 10 seconds.
  • When in Preview Mode, the client renders a clip from the beginning of the clip. If there is a StartTime or StartMarker element for this clip, the client renders the clip in Preview Mode starting at the point defined by one of these element.
  • Clips stop normally if they are shorter than the Value of the PreviewDuration element.


Attributes

Value (This is a required attribute)

The length of time the clip in the associated Entry or Ref element plays in Preview Mode. The PreviewDuration applies only to this clip, and does not affect other Entry or Ref elements in the same ASX file.

The default value for the Value attribute is inherited from the ASX element.


Parent Elements

ASX

Entry

Ref


Example
<Entry>
   <Ref href = "mms://nsserver/content/selection.asf">
   <PreviewDuration value = "0:30.0" />
   </Ref>
</Entry>


Ref

The Ref element specifies a Uniform Resource Locator (URL) for a content stream. The URL can point to either an Advanced Streaming Format (ASF or .asf) file for on-demand content, or a .nsc file that provides the player with information about a NetShow station. A NetShow station is a real-time stream. The Ref element can appear only as a child element of an Entry element.


Syntax

<Ref

Href = “URL”

/>

. . .

</Ref>


Important
  • Ref elements are processed by the client in the order that they appear in the Entry element (top to bottom). Once a connection is established to a referenced piece of content all other Ref elements in that Entry element are ignored. This is true whether the connection made is terminated normally or abnormally.


Attributes

Href

The value of the Href attribute is a URL to a NetShow on-demand ASF stream or NetShow station file (.nsc).


Number of Occurrences per Parent

One or more


Parent Elements

Entry


Child Elements

Duration

EndMarker

PreviewDuration

StartMarker

StartTime


Example
<ASX version = "3.0">
   <Entry>
   <Abstract>Clip Description</Abstract>
   <Title>Clip Title</title>
   <Author>Author’s Name</Author>
<!-- This is a comment.
There are multiple Ref elements below. Only one clip (or station if using .nsc files) will be connected to and played. If the URL in the first Ref element fails, the second Ref URL is tried. If it also fails, the third Ref URL is tried. If all three fail, the next Entry or EntryRef element in the ASX, if any, is processed.
End comment. -->
      <Ref href = "mms://nsserver/pubpt/selection1.asf" />
      <Ref href = "mms://nsserver2/pubpt/selection1.asf" />
      <Ref href = "mms://nsbackup/pubpt/selection1.asf" />
   </Entry>
</ASX>


StartMarker

The StartMarker element identifies the named or numbered index marker where Media Player is to start playing the stream referenced in the associated Entry or Ref element. When the content referenced is opened, it begins playing at the defined marker rather than the beginning of the clip. Markers are present only in stored content.


Syntax

<StartMarker

Number = “#”

Name = “marker name”

/>


Important
  • Either the Name or Number attribute is used with the StartMarker element, but not both.
  • A StartMarker element in a Ref element (where Ref is the parent element) takes precedence over a StartMarker in the Entry element encompassing that Ref element (where the Entry element is the parent of the Ref element).
  • A StartMarker element takes precedence over a StartTime element.


Attributes

Number

The numeric value of a numbered marker.

The default value for Number is the beginning of the content if on-demand, or the current position in the stream if real-time.

Name

The name of a named marker.

The default value for Number is the beginning of the content if on-demand, or the current position in the stream if real-time.


Example
<StartMarker Number = "5" />
<StartMarker Name = "MarkerC" />


StartTime

The StartTime element defines a time index into the content where the client is to start playing the stream. The StartTime element can be used only with stored, on-demand content that has been indexed.


Syntax

<StartTime

Value = “hh:mm:ss.fract”

/>


Attributes

Value

The Value attribute defines the time index at which Media Player starts playing a stream defined in the associated element.


Example
<Entry>
<!-- This is a comment.
The StartTime element below causes the client to begin playing the clip one minute and 30 seconds after the beginning.
End comment. -->
   <StartTime Value = "1:30.0" />
   <Ref href = "mms://nsserver/content/title1.asf" />
</Entry>


Title

The Title element defines a text string displayed by Media Player as the Show or Clip title, depending on the parent element of the Title element. If the parent element is ASX, the text is displayed as the Show title in the Display panel, as well as on the Show tab of the Properties dialog box. If the parent element is Entry, the text is displayed as the Clip title in the Display panel and on the Clip tab of the Properties dialog box. If a MoreInfo element is also used with the associated (parent) element, it is the Title text that the user clicks on to start a browser and navigate to the URL defined in the MoreInfo element.


Syntax

<Title>

text string

</Title>


Number of Occurrences per Parent

One


Example
<ASX version = "3.0">
   <Title>Title of the Show</title>
   <Author>Person who wrote this ASX</author>
   <Entry>
      <Title>Title of the Clip</Title>
      <Ref href = "mms://nsserver/content/title1.asf" />
   </Entry>
</ASX>


Playlists

A playlist consists of multiple Entry elements in an ASX file. Each Entry element in the ASX file is played by the client in the order they appear in the ASX file as though the user had manually opened each clip.


Example of a Simple Playlist
<ASX version = "3.0">
   <Title>Most requested titles of the day</Title>
   <Entry><Ref href = "mms://nsserver/content/title1.asf" /></Entry>
   <Entry><Ref href = "mms://nsserver/content/title2.asf" /></Entry>
   <Entry><Ref href = "mms://nsserver/content/title3.asf" /></Entry>
   <Entry><Ref href = "mms://nsserver/content/title4.asf" /></Entry>
</ASX>


Repeat

The Repeat element is used to define the number of times the client repeats the play of an Entry element or set of Entry elements.


Syntax

<Repeat

Count = “#”

>

. . .

</Repeat>


Important
  • Repeat elements may not be nested.
  • Each Entry element modified by a Repeat element is repeated the number of times defined by the Count attribute. If no Count attribute is defined, the player plays the Entry element until it is interrupted by the user. Subsequent Entry elements in the ASX file never are played.


Attributes

Count

The value of the Count attribute is an integer representing the number of times the player will repeat, or loop through, the play of an Entry element. If no Count attribute is defined in the Repeat element the content in the associated Entry element repeats an infinite number of times. A value of zero (0) does not represent an infinite loop, but instead causes the Repeat element to be ignored.


Example
<ASX version = "3.0">
   <Entry>
   <Ref href = "mms://nsserver/clips/clip1.asf" />
   </Entry>
<!-- This is a comment.
The Entry elements between the Repeat tags below each play the number of times defined by the Count attribute.
End comment. -->
   <Repeat Count = "2">
      <Entry><Ref href = "mms://nsserver/clips/clip2.asf" /></Entry>
      <Entry><Ref href = "mms://nsserver/clips/clip3.asf" /></Entry>
   </Repeat>
   <Entry>
      <Ref href = "mms://nsserver/clips/clip4.asf" />
   </Entry>
</ASX>


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


(Untitled)

About Encoder Automation

The unique features of the Encoder are exposed through Automation (formerly called OLE Automation). The exposed methods and properties allow client applications written in Microsoft® Visual Basic® or Microsoft Visual C++® to control the activities of the Encoder.

Note that the methods and properties exposed through automation do not use the same programming techniques as do Microsoft ActiveX® controls.

For more information about programming the Encoder, see Using Encoder Automation.

For more information about the specific methods and properties of the Encoder, see the Encoder Automation Reference.


ActiveMovie

ActiveMovie Object

Provides access to ActiveMovie specific properties, methods, and events specific to previous versions of the Active Movie control. This is provided for backwards compatibility purposes only.

Syntax

MediaPlayer.ActiveMovie

Remarks

This is provided for backwards compatibility purposes only.

See Also

NSPlay, Alternate Control Modes


Channel.ChannelURL Property

Returns or sets the unicast URL of the station.

Syntax

Station.ChannelURL

Remarks

A unicast URL can be specified so that clients unable to receive a multicast can rollover to a unicast. The unicast URL is a text string that uses the following formats:

  • mms://<servername>/<virtualroot>
  • http://<servername>/<virtualroot>

Where the <virtualroot> is the alias for the publishing point and path of the station. This could be an .asf file on a server, or a stream from an encoder, such as:

msbd:\\<server>\<stationname>

Example

' get the second station
Set MyStation = NSChannelMgr.Channels.Item(1)
' specify unicast rollover location
MyStation.UnicastURL = "mms://www.opera.org/bottesini"

See Also

Channel object, Channel.AutoArchive, Channel.AutoArchiveDir


Client.Address Property

Returns the address of the Client object.

Syntax

NSChannelMgr.Clients(index).Address

Example

Dim Clients
Set NoregClient = NSChannelMgr.Clients.Find( "Trondheim server" )
MsgBox "Address of Norwegian client is: " & NoregClient.Address

See Also

Client.DeliveryMode, Client.ID, Client.ChannelID, Clients collection object, Client objects


Client.ChannelId Property

Returns the station ID of the Client object.

Syntax

NSChannelMgr.Clients(index).ChannelId

Example

Dim Clients
Set NoregClient = NSChannelMgr.Clients.Find( "Trondheim server" )
MsgBox "ChannelId of Norwegian client is: " & NoregClient.ChannelId

See Also

Client.ID, Client.DeliveryMode, Client.Address, Clients collection object, Client objects


Client.DeliveryMode Property

Returns the delivery mode of the Client object.

Syntax

NSChannelMgr.Clients(index).DeliveryMode

Remarks

Following is a list of delivery mode values supported by the control:

Value | Mnemonic | Description
2 | MCM_DM_SESSIONLESS_3PH | Sessionless: data streamed via multicast with headers transferred to clients by some mechanism external to MCM.
8 | MCM_DM_DISTRIBUTION | Distribution: data streamed via a point- to- point TCP connection

Example

Dim Clients
Set NoregClient = NSChannelMgr.Clients.Find( "Trondheim server" )
Select Case NoregClient.DeliveryMode
  Case MCM_DM_SESSIONLESS str = "sessionless"
  Case MCM_DM_DISTRIBUTION str = "distribution"
Case Else str = "unknown delivery mode"
End Select
MsgBox "Norwegian client connection mode is: " & str

See Also

Client.ID, Client.ChannelID, Client.Address, Clients collection object, Client objects


Client.Disconnect Method

Disconnects a client.

Syntax

NSChannelMgr.Clients(index).Disconnect

Return Values

Returns an ActiveX HRESULT error code.

Remarks

If you remove an item from the Clients collection by using Disconnect, you must retrieve a new collection. In Visual Basic, this is done by reissuing use the Set method again to refresh the object.

Example

NSChannelMgr.Connect "LocalHost"
Dim Clients
Set Clients = NSChannelMgr.Clients
Clients(0).Disconnect
' show new number of clients
MsgBox Clients.Count & " clients now connected"
' reinitialize the collection
Set Clients = NSChannelMgr.Client

See Also

Client.ID, Client.ChannelID, Client.Address, Clients collection object, Client objects


Client.ID Property

Returns the ID of the Client object.

Syntax

NSChannelMgr.Clients(index).ID

Example

Dim Clients
Set NoregClient = NSChannelMgr.Clients.Find( "Trondheim server" )
MsgBox "ID of Norwegian client is: " & NoregClient.ID

See Also

Client.ChannelID, Client.DeliveryMode, Clients collection object, Client objects


(Untitled)

Event Notification and Authorization Plug-in Components

The NetShow server also supports the development of event notification and authorization plug-in components that enable auditing and billing for access to NetShow content. These plug-in components receive notification from the server before a task such as opening or playing a presentation is performed. The event notification and authorization plug-in components can block the server from performing the task associated with the event until it is authorized to do so by the authorization component.

One of the events supported for authorization is whether or not to skip client authentication. This means that even if an authenticator is registered with the server and enabled, the methods of the authorization component may never be called.


Legal Notice

This documentation is an early release of the final documentation, which may be changed substantially prior to final commercial release, and is confidential and proprietary information of Microsoft Corporation. It is disclosed pursuant to a non-disclosure agreement between the recipient and Microsoft. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unpublished work. © 1996-1997 Microsoft Corporation. All rights reserved.

ActiveX, JScript, Microsoft, Microsoft Press, MS, MS-DOS, Visual Basic, Visual C++, Visual J++, Windows, Win32, Win32s, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Java is a registered trademark of Sun Microsystems, Inc.

Other product and company names mentioned herein may be the trademarks of their respective owners.

Portions of Cyberbolic interface Copyright 1996-1997 by Xerox Corporation. All rights reserved.

The following statements apply only to the Python Language runtime:

Copyright © 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The Netherlands.

All Rights Reserved.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


NetShow Administrative Components

NetShow Components

[This is preliminary documentation and subject to change.]

This section of the Microsoft NetShow SDK describes functionality exposed to developers by the NetShow components. These components are used to configure, monitor, supervise, and augment the NetShow Server. NetShow Server is a set of services that unicasts or multicasts multimedia streams and files to clients. NetShow supports the following COM-compliant API sets and ActiveX controls for manipulating NetShow servers:

Component | Description
Station Manager control | Used to manage and configure a NetShow multicast server. Functionality exposed by this control (Nschmgr.ocx) includes opening, starting, stopping, and closing stations and streams This control also provides support for tracking stream properties and client connections.
Unicast Manager control | Used to manage, configure, and monitor a NetShow unicast server. Functionality exposed by this control (Nsunimgr.ocx) includes setting server limits, monitoring client preferences, monitoring server activity, and filtering the types of events fired by the control.
Authentication API | Used to create plug-in COM objects that verify the identity of clients connecting to a NetShow server.
Event Notification and Authorization API | Used to create plug-in COM objects used for billing and controlling access to NetShow content.
NetShow Encoder control | Used to convert live or stored multimedia source into an ASF stream.
File Transfer Service control | Used to broadcast files between servers, to be received over networks.


Client Object Reference

The Client object contains methods and properties for each client.

The Client object has the following method:

  • Disconnect

The Client object has the following properties:

Property | Read/Write | Description
Address | R | Returns the address of the Client object.
ChannelID | R | Returns the station ID of the Client object.
DeliveryMode | R | Returns the delivery mode of the Client object.
Id | R | Returns the ID of the Client object.

See Also

Client collection object


(Untitled)

Playlists

The Player control provides support for processing playlists. Playlists are made up of individual entries specifying a presentation contained in an Advanced Streaming redirector (ASX) file. The presentation entries are called clips. The player processes each clip in the playlist in sequence, as if they were manually opened, in order. The entire playlist of clips is referred to as a show.

This section to be completed post beta.


(Untitled)

Control Protocols

This section to be completed post beta.


SendStateChangeEvents

SendStateChangeEvents Property

This property is outdated and has been replaced by the SendOpenStateChange and SendPlayStateChange properties.


Player Control Examples

Sample | Description
VB Script Sample | This sample demontrates embedding and control of the player in a simple HTML page. Compare the VB Script in this sample with the next sample, which accomplishes the same this using JScript.
JScript Sample | This sample demontrates embedding and control of the player in a simple HTML page. Compare the JScript in this sample with the next sample, which accomplishes the same this using VB Script.
Full Sample | This sample builds on the concepts demonstrated in the simple sample. It uses text boxes to display some of the title properties. It also captures state change events and uses them to display the state of the control. A "timer" object is incorporated to update text boxes with packet status information every two seconds.

These examples illustrate how to use HTML and Visual Basic® Scripting Edition, with attributes exposed by Microsoft Media Player. They may not be fully functional within the Platform SDK framework. To download the complete suite of NetShow products, which includes working samples, visit the NetShow web site (http://www.microsoft.com/NetShow)


Programming the NetShow Unicast Manager Controls

[This is preliminary documentation and subject to change.]

Microsoft® NetShow™ Unicast Manager, packaged in the Nsunimgr.ocx file, embodies two Microsoft ActiveX® controls: NetShow Unicast Manager Admin and NetShow Unicast TraceView. The Admin control also manages various objects. This portion of the Microsoft NetShow SDK document describes the functionality exposed by these controls for creating custom administration, monitoring applications, and integrating NetShow into other software products. The document strives to lay a conceptual foundation and to provide practical guidelines for programming with the NetShow Unicast Manager controls. The discussion is divided into the following topics:

Topic | Description
About the Netshow Unicast Manager Admin Control | Introduces the architecture and utility of the NetShow Unicast Manager Admin control.
Using the Netshow Unicast Manager Admin Control | Presents a guideline to using the NetShow Unicast Manager Admin control in your applications.
Reference of the Netshow Unicast Manager Admin Control | Presents API references of the NetShow Unicast Manager Admin control, including events, methods, properties, and objects.
About the NetShow Unicast TraceView Control | Introduces the architecture and utility of the NetShow Unicast TraceView control.
Using the NetShow Unicast TraceView Control | Presents a guideline to using the NetShow Unicast TraceView control in your application.
Reference of the NetShow Unicast TraceView Control | Presents API references of the NetShow Unicast TraceView control, including events, methods, and properties.

The NetShow Unicast Manager controls require that Nsunimgr.ocx and Nsoobj.dll be present and registered on the computer.


(Untitled)

Registering Authenticators

Installing Microsoft NetShow Server version 3 or higher adds the following key to the computer’s registry for authenticators:

[HKEY_LOCAL_MACHINE\Software\Microsoft\NetShow\Servers\
\Default\Authentication]

At startup, the server checks the registry and instantiates the first enabled authenticator listed under this key.

Following is an example of the values that should be added to the Authentication key:

[HKEY_LOCAL_MACHINE\Software\Microsoft\NetShow\Servers\
\Default\Authentication\Sample Authentication Module]
"CLSID"="{16DA4310-2955-11D1-9E98-006097D2D7CF}"
"Description"="Sample Authentication module"
"Author"="Developer Name"
"Copyright"="(c) Developer 1997"
"Enabled"=dword:00000001

The class ID (CLSID) and “Enabled” values are required. The remaining values are recommended.

The server searches the registry in sequence for the first authenticator with the enabled registry value set. When an enabled authenticator is encountered, the server loads that authenticator and uses it until the server is stopped and restarted.


Registering the Event Notification and Authorization Components

Registering Event Notification and Authorization Components

Add the following key to the registry for event notification and authorization components:

[HKEY_LOCAL_MACHINE\Software\Microsoft\NetShow\Servers\
\Default\Event Notification]

At startup, the server checks the registry and instantiates each of the components listed under this key.

Following is an example of the values that should be added to the Event Notification key;

[HKEY_LOCAL_MACHINE\Software\Microsoft\NetShow\Servers\
\Default\Event Notification\Sample Billing Module]
"CLSID"="{16DA4310-2955-11D1-9E98-006097D2D7CF}"
"Description"="Sample billing module"
"Author"="Developer Name"
"Copyright"="(c) Developer 1997"
"Enabled"=dword:00000001
"Index"=dword:00000000

{Description of these values goes here!!!}

Note: Every plug-in component supports notification, support for authorization is optional. The server calls the QueryInterface method to determine if the component supports authorization.


Station Manager Control Examples

Simple_Example | A simple example showing how to use the Station Manager Control to list stations.
Multicast ASF | A more detailed example that shows how to use the Station Manager Control to create a station and start a multicast stream based on an .asf file. See the Receive Multicast ASF sample in the Media Player SDK for an example of how to receive a multicast by using an .asx file.

These examples illustrate how to use HTML and Visual Basic Scripting Edition, with attributes exposed by Microsoft NetShow. They may not be fully functional within the Platform SDK framework. To download the complete suite of NetShow products, which includes working samples, visit the NetShow web site at (http://www.microsoft.com/NetShow)


Stream.Alias Property

Returns the alias of a stream.

Syntax

NSChannelMgr.Streams(index).Alias

Example

'this code prints a list of stream aliases
For i = 0 to NSChannelMgr.Streams.Count - 1
   Document.Write NSChannelMgr.Streams(i).Alias & "<BR>"
Next i

See Also

Stream.ContentType, Stream.Seekable, Stream.Source, Stream.Title, Stream.Description, Streams collection, Stream objects


Stream.ArchiveFile Property

Returns or sets the name of the archive file of a Stream object.

Syntax

NSChannelMgr.Streams(index).ArchiveFile

Example

Dim Streams
Set MyStream = NSChannelMgr.Streams.Find( "Product Rollout" )
MsgBox "Rollout stream archived in: " & MyStream.ArchiveFile

See Also

Stream.ArchiveSize, Streams collection object, Stream objects


Stream.ArchiveSize Property

Returns or sets the size, in bytes, of the archive file of a Streamobject.

Syntax

NSChannelMgr.Stream.ArchiveSize

Example

Dim Streams
Set Streams = NSChannelMgr.Streams
MsgBox "Maximum archive size is: " & Stream(0).ArchiveSize
' set archive file size to 5 megabytes
Stream(0).ArchiveSize = 5000000

See Also

Stream.ArchiveSize, Streams collection, Stream objects


Stream.ContentType Property

Returns the content type of the stream.

Syntax

NSChannelMgr.Streams(index).ContentType

Example

Dim Streams
Set MyStream = NSChannelMgr.Streams.Find( "Product Rollout" )
MsgBox "Content type for Rollout stream is: " & _
    MyStream.ContentType

Remarks

The only valid value for this property is "ASF"

See Also

Stream.Alias, Stream.Source, Stream.Title, Stream.Description, Stream.Seekable, Streams collection, Stream objects


Stream.Description Property

Returns or sets the description of a Stream object.

Syntax

NSChannelMgr.Streams(index).Description

Example

Dim Streams
Set MyStream = NSChannelMgr.Streams.Find( "Product Rollout" )
MsgBox "Description of rollout stream is: " & MyStream.Description

See Also

Stream.Alias, Stream.ContentType, Stream.Source, Stream.Seekable


Stream.Seekable Property

Returns a Boolean value indicating whether or not the stream is seekable.

Syntax

NSChannelMgr.Streams(index).Seekable

Example

MCM.Channels.Open( "MyStation", MCM_PA_ALL_ACCESS )
Dim MyStream
' open stream "Welcome" with read access
Set MyStream = MCM.Streams.Open ("mms://nsserver/welcome.asf", _
               "Welcome", MCM_PA_READ)
MyStation.SetActiveStream Welcome
If MyStream.Seekable Then
  MyStream.Start 5000 'skip first 5 seconds
Else
  MyStream.Start 0    'start at the beginning
End If

See Also

Stream.Alias, Stream.ContentType, Stream.Source, Stream.Title, Stream.Description, Streams collection, Stream objects


Stream.Source Property

Returns the source of the stream.

Syntax

NSChannelMgr.Streams(index).Source

Example

Dim Streams
Set MyStream = NSChannelMgr.Streams.Find( "Product Rollout" )
MsgBox "Stream source is: " & MyStream.Source

See Also

Stream.ContentType, Stream.Seekable, Stream.Alias, Stream.Title, Stream.Description, Streams collection, Stream objects


Stream.Title Property

Returns or sets the title of a Stream object.

Syntax

NSChannelMgr.Streams(index).Title

Example

Dim Streams
Set MyStream = NSChannelMgr.Streams.Find( "Product Rollout" )
MsgBox "Stream Title is: " & MyStream.Title

See Also

Stream.Alias, Stream.ContentType, Stream.Source, Stream.Seekable, Stream.Description, Streams collection, Stream objects


DBAuthenticator Sample

The DBAuthenticator sample source code can be found under \NetShowRoot\SDK\Samples\Admin\Authentication\DBAuthen directory. Here, NetShowRoot is the root directory where NetShow is installed. Typically this corresponds to \Program Files\Microsoft NetShow.


NetShow Unicast Authorization Samples

Pay-Per-Minute Authorizer

This sample is installed under the \NetShowRoot\SDK\Samples\Admin\Authorization\ppm directory. Here, NetShowRoot is the root directory where NetShow is installed.


NetShow Unicast Authorization Samples

Pay-Per-View Authorizer

This sample is installed under the \NetShowRoot\SDK\Samples\Admin\Authorization\ppv directory. Here, NetShowRoot is the root directory where NetShow is installed.


NetShow Unicast Authorization Samples

Membership Authorizer

This sample is installed under the \NetShowRoot\SDK\Samples\Admin\Authorization\member directory. Here, NetShowRoot is the root directory where NetShow is installed.


Simple NetShow Station Manager Example

Simple Station Manager Example

This sample connects to a Station Manager Server and displays current station information.

Server Name: Status:

STATIONS:

STREAMS:


NetShow Stationl Manager Multicast ASF Sample

Station Manager Multicast ASF Sample

Step 1: Connect to Host

Server Name: Connected to: with Stations

Step 2: Specify Station Details

Station Name: Description: Delivery: Version:

NSC URL: Unicast URL: Source:

IP Address: IP Port: TTL: Save to NSC:

Step 3: Open Station, Wait for Stream to Open, then Start Stream

Repeat Stream Broadcast?

Stream State: Repeats:

You can use the Microsoft Media Player to receive a multicast using an ASX file. You must create an ASX file to receive a multicast using the player.


Unicast Manager Control Sample

Unicast Server Monitor Sample

This sample connects to the specified unicast server and displays current configuration settings and client information.
Server Name: Status:

Server Properties: (At time of connection)
Max Clients: Max Bandwidth: Max Bit Rate:

Event Monitoring: (At time of connection)
Server Events: Admin Events: Alert Events: Client Events:

Clients: Information about each client is listed dynamically as clients connect and disconnect from the control.

Authentication Components: These plug-in modules are used to authenticate a client's User ID and Password.

Event Notification & Authorization Components: These plug-in modules are used to monitor and control client access to NetShow content.


Unicast TraceView Control Sample

Using NetShow Unicast TraceView Control

This sample demonstrate how to use the NetShow Unicast Trace View ActiveX control in a HTML page.

First you must embed the control in your HTML page using the OBJECT tags with the CLASSID attribute set to "CLSID::24DCD5F2-6DBB-11D1-BEF5-00805FBE84A6".

Next you must connect the control to the server you wish to monitor. You can connect the TraceView control to a different server by supplying the name of the server in the Server: text field below.

Server:

The following command buttons, when clicked, call the SetServer, ClearTrace, PauseTrace, TraceProperties methods of the control, respectively.

The Trace state status:text field is used to trap the OnTraceStateChange event.

Trace state status:

To view the source of this sample, right click the mouse and then select View Source.


NetShow Unicast Administartion Utility Sample

 [Previous] [Next]

NetShow Unicast Administration Utility Sample

The NetShow Unicast Administration Utility sample illustrate the use of the #import directive to incorporate the NetShow Unicast Manager Admin control (Nsunimgr.ocx) in the development environment of Microsoft Visual C++ 5.0. You can find the sample source code, together with the Visual C++ project files, in the\NetShowRoot\SDK\Samples\Admin\UniConf directory. Here, \NetShowRoot is the root directory where NetShow is installed.

Working with ActiveX controls in Visual C++ 5.0

ActiveX controls are distributed in one or more .OCX files, which also contains the type library for a particularly control. To make an ActiveX control available to a C/C++ application, you must incorporate the control into a C/C++ source file and then create an instance of the control. In Microsoft Visual Studio you can accomplish these by carrying out the following tasks.

  • Incorporate the ActiveX control into the source code by inserting at the beginning of a C/C++ source file:
    #import “anActiveXControl.ocx”
  • Create an instance of the control using the following API:
    HRESULT hr = ControlPtr.CreateInstance(L”ProgID”);

Here the ControlPtr variable is a pointer to the specified ActiveX control. “ProgID” is the string value of the ProgID of the control. Instead of ProgID, you can also use CLSID of the control. For information on this API, see The C++ References Documentation for _com_ptr_t::CreateInstance(CLSD|ProgID, [dwClsContext]).

The #import directive is closely related to the #include C-preprocessor macro. It directs the compiler to include, at the point of import, the appropriate type library and to make the type information available for use in the application. The convention above implies that there is a copy of the .OCX file in the local working directory.

The NetShow setup application installs all the available NetShow controls in the NetShowRoot\Server directory. Here NetShowRoot is the root directory of NetShow. The default setting is C:\Program Files\Microsoft NetShow. But the system administrator can override the default value in the installation process. When in doubt, you can determine the path using the OLE/COM Object Viewer application, which is accessible from Visual Studio for Visual C++.

You can also examine all the available methods, events and properties from OLE/COM Object Viewer.

Using the NetShow Unicast Manager Admin Control in Visual C++ 5.0

The NetShow Unicast Server Manager Admin control is distributed as the nsunimgr.ocx file. The import statement thus becomes

#import “NetShowRoot\Server\nsunimgr.ocx”

If you specify NetShowRoot\Server as one of the working directories for linking with libraries in Visual Studio (You can do so after selecting the Library Files entry in the Show directories for drop-down list from the Directories pane in the Options dialog box activated from the Tools menu), you can use the following syntax:

#import <nsunimgr.ocx>

After you build the sample, you can run it by issuing from the MS-DOS console terminal the following command:

Nsumconf serverhost
[Previous] [Next]


Receive Multicast with Cancel and Error-Checking

Start the transfer with the Start Receive button. Cancel with the Cancel button. Start the receive file operation before starting the send file operation.

This demo will receive any file and store it in the directory specified by the %TEMP% environment variable. When the transfer is completed, a completion message will be displayed.

A message will be displayed when the transfer starts and when the transfer is completed. An error message will be displayed when the transfer request is made, when the transfer starts and is completed, and if the transfer is cancelled.

Note Make sure the IP address and port match the address and port of the server you want to listen to. This sample uses the following parameters:

  • IP Address: 239.230.50.50
  • IP Port: 5050

This demo contains a function (ReturnError) that takes a number corresponding to an HRESULT error code and returns a corresponding error message string.


Receive Multicast with Progress

To receive a multicast file transfer, click the Start Receive button. Cancel with the Cancel button. The transfer progress and statistics are shown below.

Bytes Transferred

Data Bytes: Total Bytes: Redundancy:

Packets Transferred

Packets: Bogus: Noise:

Start the receive file operation before starting the send file operation.

The redundancy and noise calculations are shown when the transfer is complete.

The transfer progress and statistics above shows the number of data bytes received and the number of total bytes received. Data bytes do not include any headers or forward error correction redundancy. The value for redundancy includes header information but roughly corresponds to the percent of redundancy set by the sender.

The form also shows the packets transferred and the number of bogus packets received. The "noise" is the value of the bogus packets received divided by the packets transferred. The higher the number, the more unwanted packets are on the same address.

Note Make sure the IP address and port match the address and port of the server you want to listen to. This sample uses the following parameters:

  • IP Address: 239.230.50.50
  • IP Port: 5050


Receive Multicast with Sender Verification

To receive a multicast file transfer, click the Start Receive button. Cancel with the Cancel button. Start the receive file operation before starting the send file operation. Enter a valid multicast IP address for the sender you want to receive from in the Requested Sender IP address input box below.

Requested Sender IP address:

Actual Sender IP Address:

If the sender does not have the expected IP address, the transfer is cancelled.


Receive Unicast

Receive File Transfer Unicast

To receive a unicast file transfer, click the Start Receive button. Cancel with the Cancel button. Start the receive file operation before starting the send file operation.

Total Bytes: Packets:

Sender IP: Files Received:

Sender Path: Receiver Path:

Enter a null string ("") for the IP Address and an appropriate value for the IP port. The value of 5050 is used for this example. The Type property must be set to 2.


Total FTS Demo

Total File Transfer Service Demo

Source IP: Source Port: Filter:

FilePath: Attributes: Flags:

Start Time:

Files: Percent File: Time Taken:

Current File: Size: Attributes:

Total Bytes: Data Bytes:

Packets: Bogus: Drop: Corr: Dupes:

Source Path: Destination Path:

Endpoint Address: Endpoint Port:

Source Addresss: Source Port:

Local Address: LocalPort: Local Port Used:


Simple Player Control Example (JScript)

Simple JScript Media Player Control Sample

This sample shows how to embed the NetShow player object in an HTML page and use JScript commands to manipulate the control.


Simple Media Player Control Example (VBScript)

Simple VBScript Media Player Control Sample

This sample shows how to embed the Media Player control in an HTML page and use VBScript commands to manipulate the control.


Full Player Control Example

This sample shows how to play or receive any file or broadcast.

File Name:

Clip Information: Title: Author: Copyright:

Player Status: Buffering: Play State: Open State:

Packet Statistics: Received: Lost: Reception Quality:


Simple Player Control Example

This sample shows how to play an ASF file. You have two choices.

  • One is a file on your disk named Sample.asf that can be found on c:\netshow\asfroot\sample.asf. This is the normal location of the NetShow Content Root for ASF files. If you install NetShow Server you will get this sample. If you install NetShow Tools, you can create a sample file with the NetShow ASF Editor. If you do not have a file named Sample.asf in that location, you can change the HTML code of this sample to point to any location that holds an ASF file.
  • The other is a file on the Internet called Johnk.asf that is a non-endorsement of Microsoft NetShow by John Keister of "Almost Live".


Receive Multicast ASF Sample

This sample shows how to receive a multicast ASF broadcast. See below for information about the ASX file needed.

ASX File: State:

The sample.asx file must contain a valid URL that points to the NSC file that defines the multicast. A typical .asx file might contain:

[Announcement]
Channel URL=http://HTTPSRV/sample.nsc#1
[Description]
Program Title=My Program
Program Author=My Name
Program Description=My Program
Program Copyright=1997

Change HTTPSRV to the name of the HTTP server where the .nsc file is stored. The .nsc file defines the multicast address and port to listen to, as well as other relevant information needed to play the incoming stream. Make sure to append the version number of the channel to the Channel URL.


Netshow 3.0 Beta 1 - Close Captioning Sample

This is a sample of Close Captioning using Netshow 3.0 Beta1
and SAMI (Synchronized Accessible Media Interchange) files.


NetShow/IE4.0 Demo

August 1997
Sun | Mon | Tue | Wed | Thu | Fri | Sat
27 | 28 | 29 | 30 | 31 | 1 | 2
3 | 4 | 5 | 6 | 7 | 8 | 9
10 | 11 | 12 | 13 | 14 | 15 | 16
17 | 18 | 19 | 20 | 21 | 22 | 23
24 | 25 | 26 | 27 | 28 | 29 | 30
31 | 1 | 2 | 3 | 4 | 5 | 6
September 1997
Sun | Mon | Tue | Wed | Thu | Fri | Sat
31 | 1 | 2 | 3 | 4 | 5 | 6
7 | 8 | 9 | 10 | 11 | 12 | 13
14 | 15 | 16 | 17 | 18 | 19 | 20
21 | 22 | 23 | 24 | 25 | 26 | 27
28 | 29 | 30 | 1 | 2 | 3 | 4

NetShow and Dynamic HTML


Streaming Macromedia Flash Events with NetShow

GOAL: Use a NetShow video stream to fire off Macromedia Flash animation events in another frame on the page.

To do this, we use the Flash ActiveX control, available from http://active.macromedia.com/flash2, some script to direct the events to the NetShow control, and the NetShow ActiveX control.

CODE TO PUT IN YOUR HTML: We have set up this example using frames. The right-hand frame called SWFLASH.HTM simply contains the Flash ActiveX control:

    <OBJECT ID="SWFlash" CLASSID="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
      codebase="http://active.macromedia.com/flash2/cabs/swflash.cab#version=2,0,0,11"
      width=200 height=150 align=right>
      <param NAME="Movie" VALUE="stage.swf">
      <param NAME="Play" VALUE="False">
      <param NAME="Loop" VALUE="False">
      <param NAME="Quality" VALUE="High">
      <param NAME="Scale" VALUE="ShowAll">
      <param NAME="SAlign" VALUE="TR">
      <param NAME="BGColor" VALUE="808080">
    </OBJECT>
Note that in this Flash control, we use codebase to automatically install the Flash player on computers without Flash, or with older versions of it.

In the left-hand frame called NetShow.htm, we have some JavaScript code and the NetShow ActiveX control. This JavaScript function is used to receive and interpret the events and parameters being sent from the NetShow stream. NSPlay1 refers to the NetShow Player control. This segment of code should come after the <TITLE> tag in your HTML.

    <script LANGUAGE="JavaScript" FOR="NSPlay1" EVENT="ScriptCommand(ScType, ScCmd)">
      if (ScType == "text") {
        if (ScCmd == "start")
          parent.swflash.SWFlash.Play();
        else if (ScCmd == "pause")
          parent.swflash.SWFlash.Stop();
        else if (ScCmd == "resume")
          parent.swflash.SWFlash.Play();
        else if (ScCmd == "stop") {
          parent.swflash.SWFlash.Stop();
          parent.swflash.SWFlash.Rewind();
        }
      }
    </script>

This says that if the NetShow control sends an event (scType) called text, to plug the parameter it sends with it (ScCmd) into the function, which triggers different actions based on the ScCmd type being sent at that time. For example, if the event is Text and the parameter is start then the subroutine called will execute the command parent.swflash.SWFlash.Play() which will start the Flash animation playing. Remember that this won't work unless your ASF stream contains these events and parameters in them.

Next, you need the NetShow control in the page. Here's the code we used:

    <OBJECT ID="NSPlay1" WIDTH=144 HEIGHT=96 CLASSID="CLSID:2179C5D3-EBFF-11CF-B6FD-00AA00B4E220">
      <PARAM NAME="AutoRewind" VALUE="1">
      <PARAM NAME="ClickToPlay" VALUE="0">
      <PARAM NAME="FileName" VALUE="sbnflash.asf">
      <PARAM NAME="AllowChangeControlType" VALUE="0">
      <PARAM NAME="AllowChangeDisplaySize" VALUE="0">
      <Embed type="video/x-ms-asf-plugin"
        src="sbnflash.asf"
        filename="sbnflash.asf"
        pluginspage="http://www.microsoft.com/netshow/download/player.htm"
        AutoRewind=1
        ClickToPlay=0
        AllowChangeControlType=0
        AllowChangeDisplaySize=0
        width=144
        height=96>
      </embed>
    </OBJECT>
Next, you'll need to add the events and parameters to the NetShow stream.

EVENTS AND PARAMETERS TO PUT IN YOUR NETSHOW STREAM: The preceding subroutine will wait for events and parameters from the NetShow stream to be sent to it before it will do anything. In this example, here are the events and parameters we used:

    Time | Event (scType) | Parameter (scCmd)
00:29.0 | text | start
00:40.0 | text | pause
00:56.0 | text | resume
01:05.0 | text | stop

For more information about using Flash, see the Macromedia Flash Web site.

© 1998 Microsoft Corporation. All rights reserved.


Boolean Properties (Read/Write) | Input Selection | State
AllowChangeControlType | true false |
AllowChangeDisplayMode | true false |
AllowChangeDisplaySize | true false |
AllowHideControls | true false |
AllowHideDisplay | true false |
AllowScan | true false |
AnimationAtStart | true false |
AutoRewind | true false |
AutoStart | true false |
ClickToPlay | true false |
EnableAutoProxy | true false |
EnableContextMenu | true false |
Enabled | true false |
EnableHTTP | true false |
EnableMulticast | true false |
EnablePositionControls | true false |
EnableSelectionControls | true false |
EnableTCP | true false |
EnableTracker | true false |
EnableUDP | true false |
FullScreenMode | true false |
InvokeURLs | true false |
Mute | true false |
PreviewMode | true false |
SendErrorEvents | true false |
SendKeyboardEvents | true false |
SendMouseClickEvents | true false |
SendMouseMoveEvents | true false |
SendOpenStateChangeEvents | true false |
SendPlayStateChangeEvents | true false |
SendStateChangeEvents | true false |
SendWarningEvents | true false |
ShowAudioControls | true false |
ShowCaptioning | true false |
ShowControls | true false |
ShowDisplay | true false |
ShowFullScreenControls | true false |
ShowGotoBar | true false |
ShowMarkers | true false |
ShowPositionControls | true false |
ShowSelectionControls | true false |
ShowStatusBar | true false |
ShowTracker | true false |
TransparentAtStart | true false |
UseFixedUDPPort | true false |
UseHTTPProxy | true false |
VideoBorder3D | true false |
Boolean Properties (Read) | Action | State
CanPreview |  |
CanScan |  |
CanSeek |  |
CanSeekToMarkers |  |
HasError |  |
HasMultipleItems |  |
IsBroadcast |  |
IsDurationValid |  |
Set | Input Parameter | Get | Output Value