Share via

IWMSDataContainer::GetTransferParameters

  • Article

banner art

Previous Next

IWMSDataContainer::GetTransferParameters

The server calls the GetTransferParameters method to retrieve the optimal offset and buffer size to use for read and write access.

Syntax

  HRESULT GetTransferParameters(
  QWORD  qwDesiredOffset,
  DWORD  dwDesiredMinSize,
  DWORD  dwDesiredMaxSize,
  QWORD*  pqwOffset,
  DWORD*  pdwSize,
  DWORD*  pdwBufferAlignment
);

Parameters

qwDesiredOffset

[in] QWORD containing the desired offset in bytes. This must be set to zero if the data source plug-in does not support seeking.

dwDesiredMinSize

[in] DWORD containing the desired minimum size, in bytes.

dwDesiredMaxSize

[in] DWORD containing the desired maximum size, in bytes.

pqwOffset

[out] Pointer to a QWORD containing the optimal offset in bytes for the request. The server uses this value to determine the offset value that will be set for the Read or Write method. Data containers that do not support seeking must return WMS_DATA_CONTAINER_NONSEEKABLE. For example, a live source cannot be seekable, but a file can be.

pdwSize

[out] Pointer to a DWORD containing the optimal size in bytes. The server uses this value to determine the size of the buffer required for the Read or Write method.

pdwBufferAlignment

[out] Pointer to a DWORD containing the optimal buffer alignment in bytes. The server uses this value to determine the size of the buffer address that will be set for the Read or Write method. For data source plug-ins that do not require buffer alignment, the return value must be NULL. This value must not exceed the page size of the server running Windows Media Services.

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.

Remarks

This method must be called before every call to Read or Write. The following table indicates the combinations that the server can set for the dwDesiredMinSize, dwDesiredMaxSize, and qwDesiredOffset parameters, and for the type of information that can be returned by the pqwOffset and pdwSize parameters.

dwDesiredMinSize dwDesiredMaxSize Description
Positive integer value NULL The server requires data starting at the position indicated by qwDesiredOffset and going forward as specified by dwDesiredMinSize. This specifies that the value returned for pdwSize should be close to but not less than the value specified by dwDesiredMinSize for performance reasons. The values returned for pqwOffset and pdwSize must contain the data boundaries specified by qwDesiredOffset and dwDesiredMinSize, and can contain data before or after these boundaries.
Positive integer value Positive integer value The server requires data starting at the position indicated by qwDesiredOffset and going forward as specified by dwDesiredMinSize. The value returned for pdwSize should not be greater than dwDesiredMaxSize. The value returned for pdwSize should be close to but not less than the value specified by dwDesiredMaxSize for performance reasons. The values returned for pqwOffset and pdwSize must contain the data boundaries specified by qwDesiredOffset and dwDesiredMinSize, and can contain data before or after these boundaries.
NULL Positive integer value The server requires data starting at the position indicated by qwDesiredOffset and going backward to the value specified by dwDesiredMaxSize. The value returned for pdwSize should be close to but not less than the value specified by dwDesiredMaxSize for performance reasons. The values returned for pqwOffset and pdwSize must contain the data boundaries specified by qwDesiredOffset and dwDesiredMaxSize, and can contain data before or after these boundaries.

Example Code

HRESULT STDMETHODCALLTYPE 
CDataContainer::GetTransferParameters( 
                      QWORD qwDesiredOffset,
                      DWORD dwDesiredMinSize,
                      DWORD dwDesiredMaxSize,
                      QWORD *pqwOffset,
                      DWORD *pdwSize,
                      DWORD *pdwBufferAlignment)
{
    HRESULT hr = S_OK;
    
    if( pdwBufferAlignment != NULL )
        *pdwBufferAlignment = 1;

    if( dwDesiredMinSize != 0 )
    {
        *pqwOffset = qwDesiredOffset;

        *pdwSize = dwDesiredMinSize + (DWORD)( qwDesiredOffset –
                                      *pqwOffset ); 

        if( dwDesiredMaxSize != 0 ) 
        {
            if( dwDesiredMaxSize > *pdwSize )
                *pdwSize = dwDesiredMaxSize;
            else
            {
                *pdwSize = 0;
                hr = E_FAIL;
                goto EXIT;
            }
        }
    }
    else if( dwDesiredMaxSize != 0 )
    {
        *pdwSize = dwDesiredMaxSize;
        if( qwDesiredOffset >= *pdwSize )
        {
            *pqwOffset = qwDesiredOffset - dwDesiredMaxSize;

            if( *pqwOffset > qwDesiredOffset )
            {
                *pdwSize = 0;
                hr = E_FAIL;
                goto EXIT;
            }
        }
        else
        {
            *pqwOffset = 0;
            *pdwSize = qwDesiredOffset; 
        }
    }
    else
    {
        *pdwSize = 0;
        *pqwOffset = qwDesiredOffset;
    }

EXIT:
    return( hr );
}

Requirements

Header: datacontainer.h.

Library: WMSServerTypeLib.dll.

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

See Also

Previous Next