IWMSEventAuthorizationPlugin::AuthorizeEvent

  • Article

banner art

Previous Next

IWMSEventAuthorizationPlugin::AuthorizeEvent

The AuthorizeEvent method is used by the plug-in to authorize the event requested by the server.

Syntax

  HRESULT AuthorizeEvent(
  WMS_EVENT*  pEvent,
  IWMSContext*  pUserCtx,
  IWMSContext*  pPresentationCtx,
  IWMSCommandContext*  pCommandCtx,
  IWMSEventAuthorizationCallback*  pCallback,
  VARIANT  Context
);

Parameters

pEvent

[in] Pointer to a WMS_EVENT structure containing the event to be authorized.

pUserCtx

[in] Pointer to an IWMSContext interface containing the user context.

pPresentationCtx

[in] Pointer to an IWMSContext interface containing the presentation context.

pCommandCtx

[in] Pointer to an IWMSCommandContext interface containing the command context.

pCallback

[in] Pointer to an IWMSEventAuthorizationCallback interface. The plug-in calls IWMSEventAuthorizationCallback::OnAuthorizeEvent to return a result to the server.

Context

[in] VARIANT containing a value defined by the server to identify which call to AuthorizeEvent the plug-in is responding to when it calls IWMSEventAuthorizationCallback::OnAuthorizeEvent. You must pass this value back unaltered.

Return Values

If the method succeeds, the plug-in must return S_OK. To report an error, the plug-in can return any HRESULT other than S_OK. If the plug-in uses the IWMSEventLog interface to log error information directly to the Windows Event Viewer, it is recommended that it return NS_E_PLUGIN_ERROR_REPORTED. Typically, the server attempts to make plug-in error information available to the server object model, the Windows Event Viewer, and the troubleshooting list in the details pane of the Windows Media Services MMC. However, if the plug-in uses the IWMSEventLog interface to send custom error information to the Windows Event Viewer, returning NS_E_PLUGIN_ERROR_REPORTED stops the server from also logging to the event viewer. For more information about retrieving plug-in error information, see Identifying Plug-in Errors.

If a plug-in is not able to verify access to a file because the file could not be found, it is recommended that the plug-in return NS_E_AUTHORIZATION_FILE_NOT_FOUND (0xc00d1590). The server informs the client that the file could not be found (a 201 error) rather than indicating only that access was denied (a 401 error).

Remarks

Before calling this method, the server calls GetAuthorizedEvents to retrieve an array of events that the plug-in must authorize. The server calls AuthorizeEvent when one of these events occurs.

Example Code

The following example illustrates a possible implementation of the AuthorizeEvent method for an access control list (ACL) authorization plug-in.

HRESULT STDMETHODCALLTYPE 
CACLPlugin::AuthorizeEvent(
            WMS_EVENT __RPC_FAR *pEvent,
            IWMSContext __RPC_FAR *pUserCtx,
            IWMSContext __RPC_FAR *pPresentationCtx,
            IWMSCommandContext __RPC_FAR *pCommandCtx,
            IWMSEventAuthorizationCallback __RPC_FAR *pCallback,
            VARIANT Context )
{
    HRESULT hr = S_OK;
    WMS_ACCESS_CONTROL wmsAccess = WMS_ACL_DENY_ALL;
    LPWSTR wstrUser = NULL;

    // Switch on the event type.
    switch( pEvent->Type )
    {

    case WMS_EVENT_DESCRIBE:                    // Read access
    case WMS_EVENT_OPEN:                        // Read access
    case WMS_EVENT_GET_PARAMETER:               // Read access
    case WMS_EVENT_VALIDATE_PUSH_DISTRIBUTION:  // Write access

    // Retrieve the user name from the user context.
    hr = pUserCtx->GetStringValue( const_cast<LPWSTR>( WMS_USER_NAME ), 
                                   WMS_USER_NAME_ID, 
                                   &wstrUser, 
                                   0 );
    if( SUCCEEDED( hr ) )
    {
        // Determine whether the user is in the access control list,
        // and what rights the user has.
        // The GetUserAccess funtion is user-defined.
        hr = m_AccessControl.GetUserAccess( wstrUser, wmsAccess );
        if( SUCCEEDED( hr ) )
        {
            if( ( WMS_EVENT_OPEN == pEvent->Type ) || 
                ( WMS_EVENT_DESCRIBE == pEvent->Type ) ||
                ( WMS_EVENT_GET_PARAMETER == pEvent->Type ) )
            {
                //
                // Check to see whether read access is permitted.
                //
                if( WMS_ACL_DENY_READ & wmsAccess )
                {
                    // User was denied read access.
                    hr = E_ACCESSDENIED;
                }
                else if( WMS_ACL_ALLOW_READ & wmsAccess )
                {
                    // User was granted read access.
                    hr = S_OK;
                }
                else
                {
                    // User was neither granted nor denied read access.
                    hr = HRESULT_FROM_WIN32( ERROR_NO_SUCH_USER );
                }
            }
            else
            {
                //
                // Check to see whether write access is permitted.
                //
                if( WMS_ACL_DENY_WRITE & wmsAccess )
                {
                    // User was denied write access.
                    hr = E_ACCESSDENIED;
                }
                else if( WMS_ACL_ALLOW_WRITE & wmsAccess )
                {
                    // User was granted write access.
                    hr = S_OK;
                }
                else
                {
                    // User was neither granted nor denied write access.
                    hr = HRESULT_FROM_WIN32( ERROR_NO_SUCH_USER );
                }
            }
        // Free memory.
        ::CoTaskMemFree( wstrUser );
        }
    }
    else if( DISP_E_BADINDEX == hr )
    {
        // DISP_E_BADINDEX is returned from GetStringValue if 
        // WMS_USER_NAME is not valid.
        hr = HRESULT_FROM_WIN32( ERROR_NO_SUCH_USER );
    }
    break;

    default:
        hr = S_OK;
        break;
    }

    pCallback->OnAuthorizeEvent( (long) hr, Context );
    return( S_OK );
}

Requirements

Header: event.h.

Library: WMSServerTypeLib.dll.

Platform: Windows Server 2003, Enterprise Edition; Windows Server 2003, Datacenter Edition; Windows Server 2008.

See Also

Previous Next