NAME

Win32::WindowsMedia - Base Module for Provisiong and control for Windows Media Services

VERSION

Version 0.258

SYNOPSIS

This is a module to control Windows Media services for a Windows 2003/2008 server. This is a complete change to the pre-alpha releases (0.15 and 0.16) as all functions are now in one module. To create a Windows Media control instance do the following

    use Win32::WindowsMedia;
    use strict;

    my $main =new Win32::WindowsMedia;

    my $create_server = $main->Server_Create("127.0.0.1");

The $create_server variable should return 1 on success or 0 on failure. You can then call the other functions against the main object, an example would be

    my $publishing_point = $main->Publishing_Point_Create( "127.0.0.1","andrew", "push:*", "broadcast" );

If you can create objects for multiple addresses (need to be in the same domain) you call the functions against the specific IPs. Most uses of the module will be against the local instance of Windows Media which should be 127.0.0.1

Server FUNCTIONS

Server_Create

This function create an instance to communicate with the Windows Media Server running. You can specify an IP address, however 99% of the time it should be one of the local interface IPs or localhost(127.0.0.1). It does not matter which IP is used as Windows Media services is not bound to a specific IP.

    Server_Create( "<IP>" );

Example of Use

    my $result = $main->Server_Create("127.0.0.1");

On success $result will return 1, on failure 0. If there is a failure error is set and can be retrieved.

Server_Destroy

This function destroys an instance created to communicate with the Windows Media Server running. You must specify the IP address used to create the instance.

    Server_Destroy( "<IP>" );

Example of Use

    my $result = $main->Server_Destroy("127.0.0.1");

On success $result will return 1, on failure 0. If there is a failure, error is set and can be retrieved.

Control FUNCTIONS

Publishing_Point_Create

This function creates a new publishing point on the Windows Media server specified. You need to specify the publishing point, the URL to use ( see example ) and also the type ( again see example ). This function is called through eval ( do not worry if you have no idea what this means ). If the URL specified is invalid Windows Media services will attempt to resolve it and return an invalid callback via OLE. This causes any scripts to stop without warning thus eval catches this nicely.

    Publishing_Point_Create( "<IP>", "<publishing point name>", "<URL>", "<Type>" );

    Publishing point name - Can be any alphanumeric and _ characters
    URL - can be one of push:* , or http://<ip>/<pub point> for relay
    Type - Can be one of OnDemand, Broadcast, CacheProxyOnDemand, CacheProxyBroadcast

Example of Use

    my $result = $main->Publishing_Point_Create("127.0.0.1","andrew","push:*","broadcast");

On success $result will return 1, on failure 0. If there is a failure, error is set and can be retrieved.

Publishing_Point_Remove

This function removes the publishing point name specified. You need to specify the IP and the publishing point name.

    Publishing_Point_Remove( "<IP>", "<publishing point name>" );

    my $result = $main->Publishing_Point_Remove("127.0.0.1","andrew");

On success $result will return 1, on failure 0. If there is a failure, error is set and can be retrieved.

Publishing_Point_Start

This function is only required if the publishing point in question is not using Push and auto start is off.

    Publishing_Point_Start( "<IP>", "<publishing point name>" );

Example of Use

    my $result = $main->Publishing_Point_Start("127.0.0.1","andrew");

On success $result will return 1, on failure 0. If there is a failure, error is set and can be retrieved.

Publishing_Point_Stop

This can be used on all types of publishing points and causes the source to be disconnected. If auto start is configured on the publishing point will not stop for long, max 30 seconds. If auto start on client connection it will be stopped until a client reconnects.

    Publishing_Point_Stop( "<IP>", "<publishing point name>" );

Example of Use

    my $result = $main->Publishing_Point_Stop("127.0.0.1","andrew");

On success $result will return 1, on failure 0. If there is a failure, error is set and can be retrieved.

Publishing_Point_List

This function returns an array of the currently provisioned publishing point names. You *may* find at least two which do not show up in the Windows Media adminitration panel. These are for proxy and cache use and should be ignored. You can optionally specify a partial match name which will then only return those publishing points that match.

    Publishing_Point_List( "<IP>", "<partial match>" );

Example of Use

    my @publishing_point = $main->Publishing_Point_List( "127.0.0.1", "*");

The above will return all publishing points defined.

Publishing_Point_Authorization_ACL_Add

This function adds a username to the authorization list allowed to connect to this stream. The defaults are dependent on the Parent configuration, but you can change them at this level. In order to make a change you must first delete a user, you can not add them again ( their previous entry will remain so adding them again with a different mask will not have any effect ).

    Publishing_Point_Authorization_ACL_Add ("<IP>","<publishing point name>","<pointer to hash of users");

The <hash of users> is made up of a username as the key and their mask being comma seperated entries made up from UserAccessSettings function. The allowable entries are

    ACCESSINIT
    ReadDeny
    WriteDeny
    CreateDeny
    AllDeny
    UNKNOWN
    ReadAllow
    WriteAllow
    CreateAllow
    AllAllow

    To build an entry use the following

    my %user_list = (
                'Username'      => 'ReadAllow,WriteAllow'
                'username2'     => 'ReadAllow'
                        );

    This would allow the user 'Username' to read and write to the stream ( so push ), and also allow user 'username2' to
read from the stream ( so listen ).

    You must remember the server must have these usernames configured, or accessable otherwise it will fail (silently). You
can specify a username in a domain, such if the server is configured in a domain, and do to so requires you to put the domain
before the username. To change 'Username' to be part of a domain it should be changed to 'domain\\Username' where 'domain'
is the name of the domain the user is in. Note the double \ is required.

    There is a SPECIAL user called 'Everyone' ( well it is a user defined on the server by default ) and is configured so
that if added to the publishing point it allows anyone to listen. If you do not want to use username/password for encoders
to connect you need to remove and then re-add Everyone with permissions of ReadAllow,WriteAllow.

Example of Use

    my %user_list = ( 'Everyone'        => 'ReadAllow,WriteAllow');
    $main->Publishing_Point_Authorization_ACL_Remove( "127.0.0.1", "publishing_point", \%user_list);
    $main->Publishing_Point_Authorization_ACL_Add( "127.0.0.1", "publishing_point", \%user_list);

    This will remove the username Everyone from the ACL then add it back in with read and write permissions.

Publishing_Point_Authorization_ACL_Remove

This function removes a username from the authorization list allowed to connect to this stream. The defaults are dependent on the Parent configuration, but you can change them at this level.

    Publishing_Point_Authorization_ACL_Remove ("<IP>","<publishing point name>","<pointer to hash of users");

Example of Use

    my %user_list = ( 'Everyone'        => 'ReadAllow,WriteAllow');
    $main->Publishing_Point_Authorization_ACL_Remove( "127.0.0.1", "publishing_point", \%user_list);

Publishing_Point_Authorization_ACL_List

This function lists the usernames and their permissions currently defined on the publishing point. The function requires pointer to a hash which is populated with the username as the key and the value is the numerical value of the access mask.

    Publishing_Point_Authorization_ACL_List ("<IP>","<publishing point name>","<pointer to hash");

Example of Use

    my %user_list;
    $main->Publishing_Point_Authorization_ACL_List( "127.0.0.1", "publishing_point", \%user_list);

Publishing_Point_Log_Set

This function sets up the logging facility for the publishing point named. You should only set the variables you need and leave the others as default.

    Publishing_Point_Log_Set( "<IP>","<publishing point name>","<pointer to hash for template");

Example of Use

    my %log_settings =
                (
                'Template'      => 'D:\Andrew\logs-<Y><m><d>.log',
                'Cycle'         => 'Month',
                'UseLocalTime'  => 'Yes',
                'UseBuffering'  => 'Yes',
                'UseUnicode'    => 'Yes',
                'V4Compat'      => 'No',
                'MaxSize'       => 0,
                'RoleFilter'    => 'SHAMROCK',
                'LoggedEvents'  => 'Player,Local'
                );

    $main->Publishing_Point_Log_Set("127.0.0.1","publishing_point",\%log_settings);

    Cycle can be one of None Size Month Week Day Hour

    MaxSize is in Mbytes and only used when Cycle is Size

    LoggedEvents can be None Player Distribution Local Remote Filter seperated by a comma (,)

    You can also use FreeSpaceQuota. This has a default of 10, which means 10Mbytes. The attribute means
    how much free space should be available for logging to work.

Publishing_Point_Log_Enable

This function turns on the logging plugin. If you make changes using Publishing_Point_Log_Set you need to call Publishing_Point_Log_Disable and then Publishing_Point_Log_Enable for them to take effect.

    Publishing_Point_Log_Enable("<IP>","<publishing point name>");

Example of Use

    $main->Publishing_Point_Log_Enable("127.0.0.1","publishing_point");

Publishing_Point_Log_Disable

This function turns off the logging plugin. If you make changes using Publishing_Point_Log_Set you need to call Publishing_Point_Log_Disable and then Publishing_Point_Log_Enable for them to take effect.

    Publishing_Point_Log_Disable("<IP>","<publishing point name>");

Example of Use

    $main->Publishing_Point_Log_Disable("127.0.0.1","publishing_point");

Publishing_Point_Log_Cycle

This function cycles the log file immediately rather than waiting for the log time.

    Publishing_Point_Log_Cycle("<IP>","<publishing point name>");

Example Of Use

    $main->Publishing_Point_Log_Cycle("127.0.0.1","publishing_point");

Publishing_Point_Authorization_IPAddress_Add

Publishing_Point_Authorization_IPAddress_Remove

Publishing_Point_Authorization_IPAddress_Get

Publishing_Point_General_Set

Publishing_Point_General_Get

Publishing_Point_Players_Get

Server_CoreVariable_Get

Playlist FUNCTIONS

Playlist_Jump_To_Event

This function jumps to a specific section of the current playlist. You need to make sure the playlist you are using is constructed correctly for this to work. You have to specify the server IP, publishing point name and position in the playlist (known as event). If any of the entries are incorrect or the playlist is not correct it will FAIL to jump and return no error.

    Playlist_Jump_To_Event( "<IP>", "<publishing point name>", "<playlist position>" );

Example of Use

    my $result = $main->Playlist_Jump_To_Event("127.0.0.1","andrew","position2");

On success $result will return 1, on failure 0. If there is a failure, error is set and can be retrieved. If an incorrect event, publishing point or IP are specified no error is usually returned.

AUTHOR

Andrew S. Kennedy, <shamrock at cpan.org>

BUGS

Please report any bugs or feature requests to bug-win32-windowsmedia at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Win32-WindowsMedia. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Win32-WindowsMedia

• Search CPAN

  http://search.cpan.org/dist/Win32-WindowsMedia

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 Andrew S. Kennedy, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.