B2C2, Inc. - Software Development Kit |
(Linux)
B2C2MPEG2Adapter
is the main SDK class that allows application software access to B2C2's broadband
device. This class instantiates three member classes that allow configuration
of the B2C2 tuner hardware as well as the setting of Audio, Video, Raw TS, and
IP data PIDs. B2C2MPEG2Adapter
is part of the static library that must be compiled with the application. The
class can also be used to share code easily between Windows and Linux.
(Windows)
B2C2MPEG2Adapter is an optional helper class encapsulating initialization and
handling functions (see B2C2MPEG2Filter)
as well as USB device plug-in/removal notification support. The class can also
be used to easily share code across Windows and Linux platforms.
(Windows 2000 and Windows XP with DirectX 8.1 only) While running a debug build (_DEBUG defined) of B2C2 samples or applications using the B2C2MPEG2Adapter class, you can use Microsoft's DirectX GraphEdit tool to view the sample application's filter graph. Protected (inaccessible) member functions AddFilterGraphToRot and RemoveFilterGraphFromRot are called automatically to register and unregister the newly created filter graph at the Running Object Table (ROT).
Note: To use the optional B2C2MPEG2Adapter class the source file B2C2MPEG2AdapterWin.cpp must be included and compiled with the project. To use B2C2 device notification support several initialization steps are required as described in Plug-in/Removal Device Notification (Windows Only).
Create
instance.
Example
B2C2MPEG2Adapter b2c2Adapter ("eth1");
hr = b2c2Adapter.Initialize(); if (FAILED(hr)) { fprintf(stderr, "%s failed (#%08X)\n", b2c2Adapter.GetLastErrorText(), b2c2Adapter.GetLastError()); return hr; } |
IB2C2MPEG2TunerCtrl2 *pTunerCtrl = b2c2Adapter.GetTunerControl (); IB2C2MPEG2DataCtrl4 *pDataCtrl = b2c2Adapter.GetDataControl (); IB2C2MPEG2AVCtrl2 *pAvCtrl = b2c2Adapter.GetAvControl (); |
If Initialize or other member methods fail, use GetLastError to retrieve the last-error code value. Use GetLastErrorText to retrieve the textual information.
Include the file <B2C2 SDK Root>\Include\b2c2mpeg2adapter.h and <B2C2 SDK Root>\src\B2C2MPEG2AdapterWin.cpp into your project.
Make sure that the file B2C2_Guids.h is no longer included in the current project files; include b2c2mpeg2adapter.h instead.
Remove all COM initialization and Interface querying calls from the application and replace them with calls to Initialize, GetTunerControl, GetDataControl, GetAvControl, and if required GetAudioVideoPins, GetMediaControl, GetMediaEvent, CreateTsFilter, GetTsInterfaceFilter, GetTsOutPin and ConnectTsFilterInToTsOutPin. Review the source code of the particular B2C2MPEG2Adapter functions to see which COM-specific calls and interface creations are performed.
(Windows) Plug-in/Removal Device Notification
IB2C2MPEG2Adapter methods |
Description |
Operating System (Windows, Linux) |
---|---|---|
B2C2MPEG2Adapter | Constructor of the B2C2MPEG2Adapter class. |
W, L
|
~B2C2MPEG2Adapter | Destructor of the B2C2MPEG2Adapter class. |
W, L
|
GetAudioVideoOutPins | Returns a pointer to the COM interfaces for B2C2MPEG2Filter's Audio and Video pins. |
W
|
GetAvControl | Returns pointer to the interface class IB2C2MPEG2AVCtrl2 |
W, L
|
GetDataControl | Returns pointer to the interface class IB2C2MPEG2DataCtrl4. |
W, L
|
GetFilterGraph | Returns a pointer to the DirectX filter graph interface. |
W
|
GetLastError | Returns the 32-bit error code of the error that occurred at the method. |
W, L
|
GetLastErrorText | Returns the text of the error code set by SetLastError. The text contains information concerning the function in which the error occurred. |
W, L
|
GetMediaControl | Returns a pointer to the COM interface for B2C2MPEG2Filter's filter graph media control interface. |
W
|
GetMediaEvent | Returns a pointer to the COM interface for B2C2MPEG2Filter's filter graph media event interface. |
W
|
GetTunerControl | Returns pointer to the interface class IB2C2MPEG2TunerCtrl2. |
W, L
|
CreateTsFilter | For custom filters derived from DirectShow base class IBaseFilter. Instantiates a custom filter and adds it to the filter graph. Used in conjunction with GetTsInterfaceFilter and ConnectTsFilterInToTsOutPin. |
W
|
GetTsInterfaceFilter | Returns a pointer to the specified interface filter, which is internal to the custom filter instantiated at CreateTsFilter. |
W
|
GetTsOutPin | Returns a pointer to the specified B2C2MPEG2Filter Raw TS output pin. |
W
|
ConnectTsFilterInToTsOutPin | Connects the given input pin of a custom filter previously instantiated by CreateTsFilter to the specified B2C2MPEG2Filter Raw TS output pin. |
W
|
Initialize | Checks that the SDK is correctly initialized and that the adapter is a B2C2 network adapter supported by this SDK. |
W, L
|
IsDeviceArrival | Determines whether a B2C2 was plugged in when a WM_DEVICECHANGE message is received announcing a device arrival. |
W
|
IsInitialized | Returns if B2C2MPEG2Adapter class has been initialized and connected to B2C2 broadband hardware. |
W, L
|
IsDeviceRemovalComplete | Determines whether a B2C2 was plugged in when a WM_DEVICECHANGE message from is received announcing a device removal. |
W
|
RegisterDeviceNotification | Registers a window to receive device event notifications. |
W
|
Release | Uninitializes the adapter. |
W, L
|
SetLastError | Sets the 32-bit error code for the calling thread as well as information concerning the function in which the error occurred. |
W, L
|
UnregisterDeviceNotification | Disables device event notification. |
W
|
Constructor of the B2C2MPEG2Adapter class.
Syntax
B2C2MPEG2Adapter(
const TCHAR *pszAdapterName
);
Parameters
pszAdapterName
[in] Pointer to a string specifying the adapter name of the B2C2 broadband device (i.e. "eth1"). At windows this argument is not used, but implemented to allow easy sharing of code between Windows and Linux.
Remarks
Call Initialize to perform all required initializations and to connect the B2C2MPEG2Adapter class to the B2C2 Broadband device.
On Windows the constructor also initializes the COM interface.
See also
Destructor of the B2C2MPEG2Adapter class.
Syntax
~B2C2MPEG2Adapter();
Parameters
None.
Remarks
The destructor will perform all required release calls if Release was not called before deleting the class.
On Windows the destructor also uninitializes the COM interface.
See also
(Windows only.) Returns a pointer to the COM interfaces for B2C2MPEG2Filter's Audio and Video pins.
Syntax
HRESULT GetAudioVideoOutPins(
IPin **ppPinOutAudio,
IPin **ppPinOutVideo
);
Parameters
ppPinOutAudio
[out] Pointer to B2C2MPEG2Filter's Audio COM interface.
ppPinOutVideo
[out] Pointer to B2C2MPEG2Filter's Video COM interface.
Return Value
Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.
Possible error values Description B2C2_SDK_E_NOT_INITIALIZED Device has not been initialized before calling this function. Call Initialize first. E_OUTOFMEMORY Memory for temporary pin enumeration objects could not be created.
Remarks
Initialize must be called successfully prior to calling this function. The returned interface will be automatically released on B2C2 Adapter destruction or by calling Release.
See also
Returns pointer to the interface class IB2C2MPEG2AVCtrl2.
Syntax
IB2C2MPEG2AVCtrl2 * GetAvControl();
Parameters
None.
Return Value
Returns pointer to the interface class IB2C2MPEG2AVCtrl2 if the B2C2MPEG2Adapter adapter class was successfully initialized before. Otherwise returns NULL.
Remarks
Initialize must be called successfully prior to calling this function.
Returns pointer to the interface class IB2C2MPEG2DataCtrl4.
Syntax
IB2C2MPEG2DataCtrl4 * GetDataControl();
Parameters
None.
Return Value
Returns pointer to the interface class IB2C2MPEG2DataCtrl4 if the B2C2MPEG2Adapter adapter class was successfully initialized before. Otherwise returns NULL.
Remarks
Initialize must be called successfully prior to calling this function.
(Windows only.) Returns a pointer to the DirectX filter graph interface.
Syntax
IGraphBuilder * GetFilterGraph();
Parameters
None.
Return Value
Returns a pointer to the DirectX filter graph interface if the B2C2MPEG2Adapter adapter class was successfully initialized before. Otherwise returns NULL.
Remarks
Initialize must be called successfully prior to calling this function. This interface can be used for further modifications at the filter graph (ex: attaching an Audio receiver to our Audio pin).
Returns the 32-bit error code of the error that occurred during the calling of other member functions.
Syntax
DWORD GetLastError();
Parameters
None.
Return Value
Returns the error code of the error that occurred during the calling of other member functions. If no error occurred returns 0.
Remarks
Calling GetLastError resets the error code. Information concerning the function in which the error occurred can be received through GetLastErrorText.
Returns the text of the error code (m_szLastErrorText) set by SetLastError. The text contains information concerning the function in which the error occurred.
Syntax
contst TCHAR * GetLastErrorText();
Parameters
None.
Return Value
Returns the text of the error code (m_szLastErrorText) set by SetLastError. If no error occurred returns 0.
Remarks
None.
(Windows only.) Returns a pointer to the COM interface for B2C2MPEG2Filter's filter graph media control interface. The media control interface is used to start and stop play of the stream.
Syntax
HRESULT GetMediaControl(
IMediaControl **ppMediaControl
);
Parameters
ppMediaControl
[out] Pointer to B2C2MPEG2Filter's filter graph media control COM interface.
Return Value
Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value. GetLastErrorText and GetLastError can be used to get more information if an error is returned.
Possible error values Description B2C2_SDK_E_NOT_INITIALIZED Device has not been initialized before calling this function. Call Initialize first. E_NOINTERFACE This interface is not available from the Filter Graph.
Remarks
Initialize must be called successfully prior to calling this function. The returned interface will be automatically released on B2C2 Adapter destruction or by calling Release.
See also
(Windows only.) Returns a pointer the COM interface for the B2C2MPEG2Filter's filter graph media event interface. The media event interface can be used to wait for playback for events, for example, completion of playback.
Syntax
HRESULT GetMediaEvent(
IMediaEvent **ppMediaEvent
);
Parameters
ppMediaEvent
[out] Pointer to B2C2MPEG2Filter's filter graph media event COM interface.
Return Value
Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value. GetLastErrorText and GetLastError can be used to get more information if an error is returned.
Possible error values Description B2C2_SDK_E_NOT_INITIALIZED Device has not been initialized before calling this function. Call Initialize first. E_NOINTERFACE This interface is not available from the Filter Graph.
Remarks
Initialize must be called successfully prior to calling this function. The returned interface will be automatically released on B2C2 Adapter destruction or by calling Release.
See also
Returns pointer to the interface class IB2C2MPEG2TunerCtrl2.
Syntax
IB2C2MPEG2TunerCtrl2 * GetTunerControl();
Parameters
None.
Return Value
Returns pointer to the interface class IB2C2MPEG2TunerCtrl2 if the B2C2MPEG2Adapter adapter class was successfully initialized before. Otherwise returns NULL.
Remarks
Initialize must be called successfully prior to calling this function.
Instantiates a custom filter and adds it to the filter graph. Used in conjunction with GetTsInterfaceFilter and ConnectTsFilterInToTsOutPin. The custom filter is intended to be connected to one of the Raw TS output pins ("Data 0..3") of B2C2 MPEG2Filter via the ConnectTsFilterInToTsOutPin method.
Syntax
HRESULT CreateTsFilter(
int nPin,
REFCLSID refCLSID,
IBaseFilter ** ppCustomFilter = NULL
);
Parameters
nPin
[in] Pin number of B2C2MPEG2Filter Raw TS output pin ("Data 0..3") to which the custom filter will be connected.
refCLSID
[in] CLSID (derived from DirectShow IBaseFilter class) of the custom filter to be created. This filter must be accessible by the system; for an example, see Dump.ax filter of the Test Data Filter sample.
ppCustomFilter
[out] Pointer to a pointer created by the caller. This pointer will return a pointer to the filter interface given at the second argument. This argument can be NULL if the custom filter interface is not used at the calling application. However, the filter interface pointer will be stored at the B2C2MPEG2Adapter class for use at other functions and released upon destructions. See Remarks below for further details.
Return Value
Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value. GetLastErrorText and GetLastError can be used to get more information if an error is returned.
Possible error values Description B2C2_SDK_E_NOT_INITIALIZED Device has not been initialized before calling this function. Call Initialize first. B2C2_SDK_E_INVALID_PIN The pin number given at the first argument is invalid. Valid values are 0 to 3. REGDB_E_CLASSNOTREG The specified class is not registered in the registration database. Make sure that your class is registered (in case of the Test Data Filter sample, dump.ax must be registered as described.
Remarks
Initialize must be called successfully prior to calling this function. The returned interface will be released automatically upon B2C2MPEG2Adapter destruction or by calling Release.
It is intended that the customer develop their own custom filter for processing the raw transport streams received on B2C2MPEG2Filter's Raw TS output pins. To see a working example, the Test Data Filter sample uses a custom filter, dump.ax, for capturing all input to a file.
The custom filter required for this function is a renderer filter that must be derived from the IBaseFilter class. This function instantiates the renderer filter and returns a pointer to the filter interface at the third argument. IBaseFilter is a DirectShow base class in Microsoft's DirectX SDK.
Note: Alternatively, a custom filter that is not derived from the DirectShow IBaseFilter class (and therefore not instantiated by CreateTsFilter) can still be connected to the B2C2MPEG2Filter as follows. Instantiate the custom filter at the calling application instead of using CreateTsFilter. Call GetTsOutPin to initialize the desired B2C2MPEG2Filter Raw TS output pin for connection. Retrieve the filter graph through GetFilterGraph and call its member function ConnectDirect () to connect the initialized Raw TS output pin to a custom filter input pin.
See also
GetTsInterfaceFilter, GetTsOutPin and ConnectTsFilterInToTsOutPin
Returns a pointer to the specified interface filter, which is internal to the custom filter instantiated at CreateTsFilter. Initializing this interface enables the application to modify the custom filter's settings.
Syntax
HRESULT GetTsInterfaceFilter(
int nPin,
const IID& iid,
IUnknown ** ppInterfaceFilter
);
Parameters
nPin
[in] The number of the custom filter, which is equal to the number of the B2C2MPEG2Filter Raw TS output pin ("Data 0..3") to which the custom filter will be connected.
iid
[in] Interface ID of the interface to be queried from the filter pointer instantiated at CreateTsFilter. The interface must be provided by the custom filter.
ppInterfaceFilter
[out] Pointer to a pointer created to by the caller. Returns a pointer to the interface defined at the second argument. See Remarks below for further details.
Return Value
Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value. GetLastErrorText and GetLastError can be used to get more information if an error is returned.
Possible error values Description B2C2_SDK_E_NOT_INITIALIZED Device has not been initialized before calling this function. Call Initialize first. B2C2_SDK_E_INVALID_PIN The pin number given at the first argument is invalid. Valid values are 0 to 3. B2C2_SDK_E_NO_TS_FILTER No custom renderer filter has been created before calling this function. Call CreateTsFilter first. E_NOINTERFACE This interface is not available.
Remarks
CreateTsFilter for the given Raw TS output pin must be called successfully prior to calling this function, and the filter instantiated by CreateTsFilter must provide the interface requested. The returned interface will be released automatically upon B2C2 Adapter destruction or by calling Release.
Calling this function allows the application to specify settings at the custom filter. See Test Data Filter for an example.
Returns a pointer to the specified B2C2MPEG2Filter Raw TS output pin ("Data 0..3"). This function is used if a custom filter that is not derived from the DirectShow IBaseFilter class (and therefore not instantiated by CreateTsFilter) shall be connected to the B2C2MPEG2Filter.
Syntax
HRESULT GetTsOutPin (
int nPin,
IPin **ppTsOutPin)
);
Parameters
nPin
[in] Pin number of the desired B2C2MPEG2Filter Raw TS output pin ("Data 0..3").
ppTsOutPin
[out] Pointer to a pointer created to by the caller. Returns a pointer to the Raw TS output pin specified at the first argument. See Remarks below for further details.
Return Value
Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value. GetLastErrorText and GetLastError can be used to get more information if an error is returned.
Possible error values Description B2C2_SDK_E_NOT_INITIALIZED Device has not been initialized before calling this function. Call Initialize first. B2C2_SDK_E_INVALID_PIN The pin number given at the first argument is invalid. Valid values are 0 to 3. E_OUTOFMEMORY Memory for temporary pin enumeration objects could not be created.
Remarks
Initialize must be called successfully prior to calling this function. The returned Raw TS output pin will be released automatically upon B2C2 Adapter destruction or by calling Release.
This function is used if a custom filter that is not derived from the DirectShow IBaseFilter class (and therefore not instantiated by CreateTsFilter) shall be connected to the B2C2MPEG2Filter. Instantiate this custom filter at the calling application instead of using CreateTsFilter. Call GetTsOutPin to initialize the desired B2C2MPEG2Filter Raw TS output pin for connection. Retrieve the filter graph through GetFilterGraph and call its member function ConnectDirect () to connect the initialized Raw TS output pin to a custom filter input pin.
Note: Alternatively, the B2C2MPEG2Adapter can handle the creation and release of a custom filter derived from IBaseFilter through CreateTsFilter and then connect the custom filter's input pins to B2C2MPEG2Filter's Raw TS output pins through ConnectTsFilterInToTsOutPin. For more information see the Test Data Filter sample
Connects the given input pin of a custom filter previously instantiated by CreateTsFilter to the specified B2C2MPEG2Filter Raw TS output pin ("Data 0..3").
Syntax
HRESULT ConnectTsFilterInToTsOutPin(
int nPin,
const TCHAR * szInPinName = NULL
);
Parameters
nPin
[in] Pin number of the B2C2MPEG2Filter Raw TS output pin ("Data 0..3") to which a custom filter input pin will be connected.
szInPinName
[in] Pointer to an ASCII string created to by the caller. Holds the name of the input pin of the custom filter, since the custom filter may have more than one input pin. This pin will be connected to the Raw TS output pin specified at the first argument. If the custom filter has only one input PIN, this argument can be NULL. See Remarks below for further details.
Return Value
Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value. GetLastErrorText and GetLastError can be used to get more information if an error is returned.
Possible error values Description B2C2_SDK_E_NOT_INITIALIZED Device has not been initialized before calling this function. Call Initialize first. B2C2_SDK_E_INVALID_PIN The pin number given at the first argument is invalid. Valid values are 0 to 3. B2C2_SDK_E_NO_TS_FILTER No custom renderer filter has been created before calling this function. Call CreateTsFilter first. B2C2_SDK_E_PIN_ALREADY_CONNECTED The output pin is already connected to a renderer filter input pin. B2C2_SDK_E_NO_INPUT_PIN No input pin on the custom renderer filter was found, check pin name if given. E_OUTOFMEMORY Memory for temporary pin enumeration objects could not be created.
Remarks
CreateTsFilter must be called successfully prior to calling this function. The connected pin interface of the custom filter will be automatically released upon B2C2 Adapter destruction or by calling Release.
Note: Do not use this function if the custom filter that is not derived from the DirectShow IBaseFilter class (and therefore not instantiated by CreateTsFilter). Instead, call GetTsOutPin to initialize the desired B2C2MPEG2Filter Raw TS output pin for connection. Retrieve the filter graph through GetFilterGraph and call its member function ConnectDirect () to connect the initialized Raw TS output pin to a custom filter input pin.
Checks that the SDK is correctly initialized and that the adapter is a B2C2 network adapter supported by this SDK.
Syntax
HRESULT Initialize();
Parameters
None.
Return Value
Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.
Possible error values Description OSREGDB_E_CLASSNOTREG The specified class is not registered in the registration database. Make sure that Broadband4PC is correctly installed and that the USB device, if used, is connected. WE_NOINTERFACE One of the control interface classes is not available. Make sure that you have the latest version of Broadband4PC installed. WB2C2_SDK_E_CREATE_INTERFACE Not all interfaces could be created correctly. Make sure that you have the latest version of Broadband4PC installed. W, LB2C2_SDK_E_UNSUPPORTED_DEVICE The given network device is no B2C2 Broadband device. L
Remarks
If the function succeeds, GetTunerControl, GetAvControl, and GetDataControl will return valid pointers to their respective interface classes. Otherwise these functions return NULL. If the function fails, the member pointers must not be used. If the function fails, information concerning the error can be received through GetLastError and GetLastErrorText. To uninitialize the adapter, call Release.
Audio and Video features are not initialized automatically. To use Audio and Video features, call GetAudioVideoOutPins, GetMediaControl, and GetMediaEvent.
(Windows only.) Determines whether a B2C2 adapter was plugged in when a WM_DEVICECHANGE message is received announcing a device arrival.
Syntax
int IsDeviceArrival(
WPARAM wChangeEvent,
LPARAM lData
);
Parameters
wChangeEvent
[in] The device-change event such as the device arrival.
lData
[in] A pointer to a structure identifying the particular device inserted.
Return Value
Return TRUE.
Remarks
None.
Returns a nonzero value if B2C2MPEG2Adapter class has been initialized and connected to B2C2 broadband hardware.
Syntax
BOOL IsInitialized();
Parameters
None.
Return Value
Returns a nonzero value if B2C2MPEG2Adapter class has been initialized and connected to B2C2 broadband hardware.
Remarks
None.
(Windows only.) Determines whether a B2C2 was plugged in when a WM_DEVICECHANGE message from is received announcing a device removal.
Syntax
int IsDeviceRemovalComplete(
WPARAM wChangeEvent,
LPARAM lData
);
Parameters
wChangeEvent
[in] The device-change event such as the device arrival.
lData
[in] A pointer to a structure identifying the particular device inserted.
Return Value
Return TRUE.
Remarks
None.
(Windows only.) Registers a window to receive device event notifications.
Syntax
BOOL RegisterDeviceNotification(
HANDLE hRecipient
);
Parameters
hRecipient
[in] Handle to the window that will receive device events.
Return Value
Returns a nonzero value if the function succeeds.
Remarks
None.
See also
Uninitializes the adapter.
Syntax
void Release();
Parameters
None.
Return Value
None.
Remarks
After calling Release, GetTunerControl, GetAvControl, and GetDataControl can no longer be used (will return NULL). Initialize can be called again to re-initialize the adapter without recreating the B2C2MPEG2Adapter object.
Sets the 32-bit error code for the calling thread as well as information concerning the function in which the error occurred. Used for an Initialize error.
Syntax
void SetLastError(
const TCHAR * szErrText,
DWORD dwErrCode
);
Parameters
szErrText
[in] Pointer to a variable holding the error text: information concerning the function in which the error occurred.
dwErrCode
[in] Specifies the last-error code for the thread.
Return Value
None.
Remarks
Applications can retrieve the value saved by this function by using the GetLastError function.
(Windows only.) Disables device event notification.
Syntax
BOOL UnregisterDeviceNotification();
Parameters
None.
Return Value
Returns a nonzero value if the function succeeds.
Remarks
None.
See also