B2C2, Inc. - Software Development Kit

IB2C2MPEG2DataCtrl4

  IB2C2MPEG2DataCtrl4      
  Call Sequences and Overview      
  Scrambling Control Methods      
  Methods by Interface      
  Methods by Functionality      
           

A channel typically contains multiple program streams of packeted information identified by PID (Program Identifier). An IP data stream is a stream carrying IP packets. A Raw TS stream is any stream (regardless of content) arbitrarily selected by its PID. After a channel is locked onto by a tuner, the desired program is selected by setting its PID.

IB2C2MPEG2DataCtrl4 supports terrestrial, satellite and cable tuners. IB2C2MPEG2DataCtrl4 methods enable an application to configure PID parameters for receiving IP data and Raw Transport Stream (Raw TS) data. Additionally, IB2C2MPEG2DataCtrl4 methods can set the broadband device's unicast MAC address and multicast groups and monitor IP data reception statistics.

In Windows, IB2C2MPEG2DataCtrl4 is an interface implemented on the B2C2MPEG2Filter, a DirectShow compatible filter.

In Linux, IB2C2MPEG2DataCtrl4 is instantiated as a member of the overall class B2C2MPEG2Adapter, which controls B2C2's broadband device.

Call Sequences and Overview

The following describes the call sequence that must be followed by the application programs for the management of PIDs. A distinction must be made between IP PIDs and raw transport stream PIDs, since only IP data is processed in the network stack while other data is sent elsewhere.

   
1.

At any point, new PIDs can be added. The AddIpPIDs method allows IP PIDs to be sent to the network stack. Audio and Video PIDs are set at IB2C2MPEG2AVCtrl2::SetAudioVideoPIDs.

Windows:
The AddPIDsToPin method allows raw transport stream PIDs received from the driver to be sent to
B2C2MPEG2Filter.

Linux:
The AddTsPIDs method allows raw transport stream PIDs received from the driver to be sent to the Callback interface.

   
2. PIDs may be deleted at any time using the DeletePIDsFromPin (Windows), DeleteTsPIDs (Linux) or DeleteIpPIDs call. (Similarly, Audio and Video PIDs are deleted at IB2C2MPEG2AVCtrl2::DeleteAudioVideoPIDs.) If a PID has been added more than once, it will remain active until it is deleted the same number of times as it has been added.
   
3. PurgeGlobalPIDs will remove all occurrences of every IP PID in the system, regardless of the number of times a PID has been added. (DeleteIpPIDs only deletes one occurrence.)
   
4. GetIpState and GetTsState can be called at any time to obtain a list of all IP and TS PIDs that have been added and not subsequently deleted or purged.
 

Scrambling Control Methods

The current version of B2C2's broadband devices may support three ways of setting keys for decrypting incoming packets. The device stores a list of keys with different ways to define whether the key will be used for decrypting. To determine whether and which key types are supported, the function GetKeyCount can be used. The three different ways to specify the key type are:

Keys can be added to the device by using the function AddKey. DeleteKey can be used to delete keys currently set and PurgeKeys can be used to delete all currently set keys. The type and PID values for the current keys can be retrieved by calling GetKeysInUse. For security, calling GetKeysInUse will not return the values of the actual key. GetKeysInUse returns the keys in the order of priority (highest to lowest).

Note: Adding a PID key with AddKey will not automatically add the PID to the receiver. Data can only be received after the PID is added by calling one of the functions AddIpPIDs, IB2C2MPEG2DataCtrl3::AddTsPIDs (Linux), IB2C2MPEG2DataCtrl2::AddPIDsToPin (Windows) or IB2C2MPEG2AVCtrl::SetAudioVideoPIDs depending on the stream type.

Note: Keys are not protected against multi-application access. Therefore one application can delete or change keys set by another application, which will stop the reception of data by the other application. Applications should make sure to delete only keys set by the application and use PurgeKeys with care, since PurgeKeys will delete all keys regardless of type and which application set them.

Methods by Interface

For backwards compatibility IB2C2MPEG2DataCtrl, IB2C2MPEG2DataCtrl2 and IB2C2MPEG2DataCtrl3 are defined. But the derived class IB2C2MPEG2DataCtrl4 supports all methods from previous versions IB2C2MPEG2DataCtrl through IB2C2MPEG2DataCtrl3. Methods for all versions are shown in the table.

IUnknown methods

Description

x
Operating System
(Windows, Linux)
QueryInterface Retrieves pointers to supported interfaces.   W
AddRef Increments the reference count.   W
Release Decrements the reference count.   W

IB2C2MPEG2DataCtrl methods

Description

Protocol
Operating System
(Windows, Linux)
AddIpPIDs Sets IP PID values of interest.
IP
W, L
AddPIDs Sets PID values of interest. Obsolete. Use AddPIDsToPin (Windows) or AddTsPIDs (Linux) method.
Transport Stream
W
DeleteIpPIDs Deletes IP PID values.
IP
W, L
DeletePIDs Deletes PID values. Obsolete. Use DeletePIDsFromPin (Windows) or DeleteTsPIDs (Linux) method.
Transport Stream
W
GetDataReceptionStats Retrieves data reception statistics (ratio of correctly recovered packets to total packets).
TS, IP
W
GetGlobalPIDs

Retrieves list of currently set IP PIDs.

IP
W, L
GetIpPIDs Gets list of all IP PIDs that have been added and not subsequently deleted or purged.
IP
W, L
GetMaxGlobalPIDCount

Identifies maximum number of available IP PIDs.

IP
W, L
GetMaxIpPIDCount Retrieves count of maximum simultaneous IP PIDs allowed.
IP
W, L
GetMaxPIDCount

Retrieves count of maximum simultaneous raw transport stream PIDs allowed.

Transport Stream
W, L
Initialize Creates connection to Data Control.
All
L
PurgeGlobalPIDs Deletes all IP PIDs currently active in the tuner.
IP
W, L
ResetDataReceptionStats Defines start time for GetDataReceptionStats calculation. TS, IP W

IB2C2MPEG2DataCtrl2 methods

Description

Protocol
Operating System
(Windows, Linux)
AddPIDsToPin Sets raw transport stream PID values of interest and associates them with B2C2MPEG2Filter output pins.
Transport Stream
W
DeletePIDsFromPin Deletes raw transport stream PID values and dissociates them from B2C2MPEG2Filter output pins.
Transport Stream
W

IB2C2MPEG2DataCtrl3 methods

Description

Protocol
Operating System
(Windows, Linux)
AddMulticastMacAddress Adds the given multicast MAC addresses.
IP
W, L
AddTsPIDs Sets raw transport stream PID values of interest.
Transport Stream
W, L
DeleteMulticastMacAddress Deletes the given multicast MAC addresses.
IP
W, L
DeleteTsPIDs Deletes raw transport stream PID values.
Transport Stream
W, L
GetBufferPos (See Linux DDK documentation)   L
GetIpState Returns the current IP settings.
IP
W, L
GetMulticastMacAddressList Gets the list of currently set multicast MAC addresses.
IP
W, L
GetReceivedDataIp Gets count of bytes and IP packets received. All W, L
GetTsState Returns the current transport stream settings.
Transport Stream
W, L
GetUnicastMacAddress Gets the current unicast MAC address.
IP
W, L
RestoreUnicastMacAddress Restores the unicast MAC address to the device default.
IP
W, L
SetUnicastMacAddress Sets the unicast MAC address.
IP
W, L

IB2C2MPEG2DataCtrl4 methods

Description

Protocol
Operating System
(Windows, Linux)
GetHardwareMacAddress Returns the MAC address of the B2C2 adapter.
IP
W, L
SetTableId Sets the datagram table ID.
IP
W, L
GetTableId Gets the datagram table ID.
IP
W, L
GetKeyCount Determines whether and how many keys in total and of each type can be set.
Conditional Access
W, L
GetKeysInUse Gets a list of key types and PIDs for which keys are currently set.
Conditional Access
W, L
AddKey Adds a key for decrypting packets.
Conditional Access
W, L
DeleteKey Deletes a key for decrypting packets.
Conditional Access
W, L
PurgeKeys Delete all keys currently set.
Conditional Access
W, L

Methods by Functionality

List of methods sorted by functionality. This is not a complete list of all data control methods.

General methods

Description

Operating System
(Windows, Linux)
Initialize Creates connection to Data Control. L
GetBufferPos (See Linux DDK documentation) L
SetTableId Sets the datagram table ID. W, L
GetTableId Gets the datagram table ID. W, L

Raw Transport Stream PID handling methods

Description

Operating System
(Windows, Linux)
AddPIDs Sets PID values of interest. Obsolete. Use AddPIDsToPin (Windows) or AddTsPIDs (Linux) method. W
DeletePIDs Deletes PID values. Obsolete. Use DeletePIDsFromPin (Windows) or DeleteTsPIDs (Linux) method. W
AddPIDsToPin Sets raw transport stream PID values of interest and associates them with B2C2MPEG2Filter output pins. W
DeletePIDsFromPin Deletes raw transport stream PID values and dissociates them from B2C2MPEG2Filter output pins. W
AddTsPIDs Sets raw transport stream PID values of interest. W, L
DeleteTsPIDs Deletes raw transport stream PID values. W, L
GetMaxPIDCount

Retrieves count of maximum simultaneous raw transport stream PIDs allowed.

W, L
GetTsState Returns the current transport stream settings. W, L

IP PID handling methods

Description

Operating System
(Windows, Linux)
AddIpPIDs Sets IP PID values of interest. W, L
DeleteIpPIDs Deletes IP PID values. W, L
GetIpPIDs Gets list of all IP PIDs that have been added and not subsequently deleted or purged. W, L
GetGlobalPIDs

Retrieves list of currently set IP PIDs.

W, L
GetMaxGlobalPIDCount

Identifies maximum number of available IP PIDs.

W, L
GetMaxIpPIDCount Retrieves count of maximum simultaneous IP PIDs allowed. W, L
PurgeGlobalPIDs Deletes all IP PIDs currently active in the tuner. W, L
GetIpState Returns the current IP settings. W, L

MAC address handling methods

Description

Operating System
(Windows, Linux)
GetHardwareMacAddress Returns the MAC address of the B2C2 adapter. W, L
GetMulticastMacAddressList Gets the list of currently set multicast MAC addresses. W, L
AddMulticastMacAddress Adds the given multicast MAC addresses. W, L
DeleteMulticastMacAddress Deletes the given multicast MAC addresses. W, L
GetUnicastMacAddress Gets the current unicast MAC address. W, L
SetUnicastMacAddress Sets the unicast MAC address. W, L
RestoreUnicastMacAddress Restores the unicast MAC address to the device default. W, L

Statistics handling methods

Description

Operating System
(Windows, Linux)
GetDataReceptionStats Retrieves data reception statistics (ratio of correctly recovered packets to total packets). W
ResetDataReceptionStats Defines start time for GetDataReceptionStats calculation. W
GetReceivedDataIp Gets count of bytes and IP packets received. W, L

Key handling methods

Description

Operating System
(Windows, Linux)
GetKeyCount Determines whether and how many keys in total and of each type can be set. W, L
GetKeysInUse Gets a list of key types and PIDs for which keys are currently set. W, L
AddKey Adds a key for decrypting packets. W, L
DeleteKey Deletes a key for decrypting packets. W, L
PurgeKeys Delete all keys currently set. W, L


TRANSPORT STREAM PROTOCOL METHODS

The following methods are for use with the Transport Stream protocols:


IB2C2MPEG2DataCtrl3::AddPIDs

The AddPIDs function is obsolete and is implemented for backwards compatibility only. Current version uses AddPIDsToPin (Windows) or AddTsPIDs (Linux) method.

Return to Top

(Windows only.) Sets raw transport stream PID values of interest to the application.

Syntax

HRESULT AddPIDs(

long lCount,

long * plPIDArray

);

Parameters

lCount

[in] Number of PID(s) being passed in using the array (2nd argument). Must not be larger than value returned by GetMaxPIDCount.

plPIDArray

[in] Array of length lCount, where each element is set to a PID of interest.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The application should set the elements of the array plPIDArray to contain the PID(s) that it is interested in processing, and pass the array size via lCount.

See also

AddPIDsToPin; AddTsPIDs; DeletePIDs; GetMaxPIDCount


IB2C2MPEG2DataCtrl3::AddPIDsToPin

Return to Top

(Windows only.) Sets raw transport stream PID values of interest to the application and associates these PIDs with B2C2MPEG2Filter output pins.

Syntax

HRESULT AddPIDsToPin(

long * plNumPID,

long * plPIDArray,

long lDataPinIndex

);

Parameters

plNumPID

[in/out] Pointer to a variable created by the caller. (In) Variable holds the number of PIDs to be added given by the second argument.(Out) Variable holds the number of PIDs added.

plPIDArray

[in] Pointer to array created by the caller. Array holds the PIDs to be added. Must not be smaller than the value passed by the first argument.

lDataPinIndex

[in] Zero based index of the B2C2MPEG2Filter output pin to which you want to add the PIDs of the second argument.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The application should set the elements of the array plPIDs to contain the PID(s) that it is interested in processing and pass the array size via plNumPID. PIDs can be added dynamically. Maximum number of PIDs to be added cannot be larger than the value returned by GetMaxPIDCount.

See also

AddTsPIDs; DeletePIDsFromPin; GetMaxPIDCount


IB2C2MPEG2DataCtrl3::AddTsPIDs

Return to Top

(Linux or Windows) Sets raw transport stream PID values of interest to the application.

Syntax

HRESULT AddTsPIDs(

long lCount,

long * plPIDArray

);

Parameters

lCount

[in] Number of PID(s) being passed in using the array (2nd argument). Must not be larger than value returned by GetMaxPIDCount.

plPIDArray

[in] Pointer to an array created by the caller. Array holds each PID of interest. Must not be smaller than the value passed by the first argument.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The application should set the elements of the array plPIDArray to contain the PID(s) that it is interested in processing, and pass the array size via lCount. In Windows this function is the same as AddPIDsToPin for Pin 0.

See also

AddPIDsToPin; DeleteTsPIDs; GetMaxPIDCount


IB2C2MPEG2DataCtrl3::DeletePIDs

The DeletePIDs function is obsolete and is implemented for backwards compatibility only. Current version uses DeletePIDsFromPin (Windows) or DeleteTsPIDs (Linux) method.

Return to Top

(Windows only.) Deletes raw transport stream PID values that the application no longer wants processed.

Syntax

HRESULT DeletePIDs(

long lCount,

long * plPIDArray

);

Parameters

lCount

[in] Number of PID(s) being passed in using the array (2nd argument). Must not be larger than value returned by GetMaxPIDCount.

plPIDArray

[in] Array of length lCount, where each element is set to a PID that no longer needs to be processed

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The application should set the elements of the array plPIDArray to contain the PID(s) that should no longer be processed, and pass the array size via lCount.

See also

AddPIDs; DeletePIDsFromPin; DeleteTsPIDs; GetMaxPIDCount


IB2C2MPEG2DataCtrl3::DeleteMulticastMacAddress

Return to Top

Deletes the given multicast MAC addresses.

Syntax

HRESULT DeleteMulticastMacAddress(

tMacAddressList * pMacAddrList

);

Parameters

pMacAddrList

[in] Pointer to the structure tMacAddressList created by the caller. (tMacAddressList is defined in header file b2c2_defs.h delivered as part of the SDK.) The member lCount holds the number of MAC addresses to delete; the first 1Count members of the aabtMacAddr[B2C2_SDK_MAC_ADDR_LIST_MAX][B2C2_SDK_MAC_ADDR_SIZE] array will be deleted. The maximum number of MAC addresses held by the aabtMacAddr array is defined at B2C2_SDK_MAC_ADDR_LIST_MAX; therefore, lCount must not be larger than B2C2_SDK_MAC_ADDR_LIST_MAX. The number of bytes per MAC address in the array is defined at B2C2_SDK_MAC_ADDR_SIZE, which specifies the size of an array member.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

Example

unsigned char newMac[B2C2_SDK_MAC_ADDR_SIZE] = { 0x01, 0x00, 0x5E, 0x01, 0x01, 0x01 };

tMacAddressList addMacAddrList;
memset (&delMacAddrList, 0x00, sizeof (delMacAddrList));
memcpy (delMacAddrList.aabtMacAddr [delMacAddrList.lCount++], delMac, B2C2_SDK_MAC_ADDR_SIZE);

HRESULT hr = pDataCtrl->DeleteMulticastMacAddress (&delMacAddrList); 

if (FAILED (hr))
{
	// error handling
}

IB2C2MPEG2DataCtrl3::DeletePIDsFromPin

Return to Top

(Windows only.) Deletes raw transport stream PID values that the application no longer wants processed and dissociates the PIDs from their B2C2MPEG2Filter output pins.

Syntax

HRESULT DeletePIDs(

long lNumPID,

long * plPIDs,

long lDataPinIndex

);

Parameters

lNumPID

[in] Variable showing number of PIDs to be deleted. PIDs are defined in the second argument.

plPIDs

[in] Pointer to array created by the caller. Array holds the PIDs to be deleted. Array must not be smaller than the number given by the first argument.

lDataPinIndex

[in] Zero based index of the B2C2MPEG2Filter output pin from which you want to delete the PIDs of the second argument.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The application should set the elements of the array plPIDs to contain the PID(s) that should no longer be processed and pass the array size via lNumPID. PIDs can be deleted dynamically.

See also

AddPIDsToPin; DeleteTsPIDs


IB2C2MPEG2DataCtrl3::DeleteTsPIDs

Return to Top

(Linux or Windows) Deletes raw transport stream PID values that the application no longer wants processed.

Syntax

HRESULT DeleteTsPIDs(

long lCount,

long * plPIDArray

);

Parameters

lCount

[in] Number of PID(s) being passed in using the array (2nd argument). Must not be larger than value returned by GetMaxPIDCount.

plPIDArray

[in] Pointer to an array created by the caller. Array holds each PID that no longer needs to be processed. Size must not be smaller than value passed by the first argument.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The application should set the elements of the array plPIDArray to contain the PID(s) that should no longer be processed, and pass the array size via lCount. In Windows this function is the same as DeletePIDsFromPin for Pin 0.

See also

AddTsPIDs; DeletePIDsFromPin


IB2C2MPEG2DataCtrl3::GetMaxPIDCount

Return to Top

Retrieves count of maximum simultaneous raw transport stream PIDs allowed. This value is currently 39.

Syntax

HRESULT GetMaxPIDCount(

long * plCount

);

Parameters

plCount

[out] Pointer to long variable created by the caller. Variables will hold the value for maximum simultaneous PIDs.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2DataCtrl3::GetTsState

Return to Top

Returns current transport stream settings in terms of raw transport stream PIDs open or running, where "open" means PID set, and "running" means started, not currently stopped.

Syntax

HRESULT GetTsState(

long * plOpen,

long * plRunning,

long * plCount,

long * plPIDArray

);

Parameters

plOpen

[out] Pointer to long variable created by the caller. Variable will hold the count of currently open TS streams. A value of 0 indicates that no TS streams are open. Pass NULL for this argument if no return is desired.

plRunning

[out] Pointer to long variable created by the caller. Variable will hold the count of currently running TS streams. A value of 0 indicates that no TS streams are running. Pass NULL for this argument if no return is desired.

plCount

[in/out] Pointer to a long variable created by the caller. (Input) variable holds the size of the PID array. (Output) variable will hold the number of PID(s) being used in the second argument. Pass NULL for this argument and plPIDArray if no return is desired.

plPIDArray

[out] Pointer to an array created by the caller. In the array each element will be set to a PID of interest. Must not be smaller than the value passed by the third argument. Use GetMaxPIDCount to determine the maximum possible number of PIDs. Pass NULL for this argument and plCount if no return is desired.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

 


IP METHODS

The following methods are for use with Internet Protocol (IP) packets.


IB2C2MPEG2DataCtrl3::AddMulticastMacAddress

Return to Top

Adds the given multicast MAC addresses.

Syntax

HRESULT AddMulticastMacAddress(

tMacAddressList * pMacAddrList

);

Parameters

pMacAddrList

[in] Pointer to the structure tMacAddressList created by the caller. (tMacAddressList is defined in header file b2c2_defs.h delivered as part of the SDK.) The structure member lCount holds the number of MAC addresses to delete; the first 1Count members of the aabtMacAddr[B2C2_SDK_MAC_ADDR_LIST_MAX][B2C2_SDK_MAC_ADDR_SIZE] array will be added. The maximum number of MAC addresses held by the aabtMacAddr array is defined at B2C2_SDK_MAC_ADDR_LIST_MAX; therefore, lCount must not be larger than B2C2_SDK_MAC_ADDR_LIST_MAX. The number of bytes per MAC address in the array is defined at B2C2_SDK_MAC_ADDR_SIZE.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

Example

unsigned char newMac[B2C2_SDK_MAC_ADDR_SIZE] = { 0x01, 0x00, 0x5E, 0x01, 0x01, 0x01 };

tMacAddressList addMacAddrList;      
memset (&addMacAddrList, 0x00, sizeof (addMacAddrList)); 
memcpy (addMacAddrList.aabtMacAddr [addMacAddrList.lCount++], newMac, B2C2_SDK_MAC_ADDR_SIZE);

HRESULT hr = pDataCtrl->AddMulticastMacAddress (&addMacAddrList);

if (FAILED (hr)) 
{
	// error handling 
}

IB2C2MPEG2DataCtrl3::AddIpPIDs

Return to Top

Sets IP PID values of interest to the application.

Syntax

HRESULT AddIpPIDs(

long lSize,

long * plPIDArray

);

Parameters

lSize

[in] Long variable that passes the size of the array specified in the second argument. Must not be larger than value returned by GetMaxIpPIDCount.

plPIDArray

[in] Pointer to an array created by the caller. In the array each element specifies a PID to be added. Array must not be smaller than the value passed by the first argument.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

See also

DeleteIpPIDs; GetMaxIpPIDCount


IB2C2MPEG2DataCtrl3::DeleteIpPIDs

Return to Top

Deletes IP PID values that the application no longer wants processed.

Syntax

HRESULT DeleteIpPIDs(

long lSize,

long * plPIDArray

);

Parameters

lSize

[in] Long variable used to pass the size of the array specified in the second argument. Must not be larger than value returned by GetMaxIpPIDCount.

plPIDArray

[in] Pointer to an array created by the caller. In the array each element specifies a PID to be deleted.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

See also

AddIpPIDs; GetMaxIpPIDCount


IB2C2MPEG2DataCtrl3::GetGlobalPIDs

Return to Top

Retrieves list of currently set IP PIDs.

Syntax

HRESULT GetGlobalPIDs(

long * plCount

long * plPIDArray

);

Parameters

plCount

[out] Pointer to long variable created by caller. Variable will hold count of how many PIDs are used in this array.

plPIDArray

[out] Pointer to array created by the caller. In the array each element specifies a PID. Array must not be smaller than the value returned by GetMaxGlobalPIDCount.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

See also

GetMaxGlobalPIDCount


IB2C2MPEG2DataCtrl3::GetIpPIDs

Return to Top

Gets a list of all IP PIDs that have been added that have not been subsequently deleted or purged.

Syntax

HRESULT GetIpPIDs(

long * plSize,

long * plPIDArray

);

Parameters

plSize

[out] Pointer to a long variable created by the caller. Variable will hold the size of the array specified in the second argument.

plPIDArray

[out] Pointer to an array created by the caller. In the array each element will specify a currently active PID. Must not be smaller than the value returned by GetMaxIpPIDCount.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

See also

AddIpPIDs; DeleteIpPIDs; GetMaxIpPIDCount; GetIpState


IB2C2MPEG2DataCtrl3::GetIpState

Return to Top

Returns current IP settings in terms of IP PID streams open or running, , where "open" means PID set, and "running" means started, not currently stopped.

Syntax

HRESULT GetIpState(

long * plOpen,

long * plRunning,

long * plCount,

long * plPIDArray

);

Parameters

plOpen

[out] Pointer to a long variable created by the caller. Variable will hold the count of currently open IP streams. A value of 0 indicates that no IP streams are open. Pass NULL for this argument if no return is desired.

plRunning

[out] Pointer to a long variable created by the caller. Variable will hold the count of currently running IP streams. A value of 0 indicates that no IP streams are running. Pass NULL for this argument if no return is desired.

plCount

[in/out] Pointer to a long variable created by the caller. (Input) Variable holds the size of the PID array. (Output) Variable will hold the number of PID(s) being used in the fourth argument. Pass NULL for this argument and plPIDArray if no return is desired.

plPIDArray

[out] Pointer to an array created by the caller. In the array each element will be set to a PID of interest. Must not be smaller than the value passed by the third argument. Use GetMaxIpPIDCount to determine the maximum possible number of PIDs. Pass NULL for this argument and plCount if no return is desired.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2DataCtrl3::GetMaxGlobalPIDCount

Return to Top

Shows the maximum number of available IP PIDs.

Syntax

HRESULT GetMaxGlobalPIDCount(

long * plMaxPIDCount

);

Parameters

plMaxPIDCount

[out] Pointer to a long variable created by the user. Variable will hold maximum number of available PIDs.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2DataCtrl3::GetMaxIpPIDCount

Return to Top

Retrieves count of maximum simultaneous IP PIDs allowed. This value is currently 33.

Syntax

HRESULT GetMaxIpPIDCount(long * plCount);

Parameters

plCount

[out] Pointer to long variable created by the caller. Variable will hold the value for maximum simultaneous IP PIDs.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2DataCtrl3::GetMulticastMacAddressList

Return to Top

Gets the list of currently set MAC addresses.

Syntax

HRESULT GetMulticastMacAddressList(

tMacAddressList * pMacAddrList

);

Parameters

pMacAddrList

[in] Pointer to the structure tMacAddressList created by the caller. (tMacAddressList is defined in header file b2c2_defs.h delivered as part of the SDK.) The first 1Count members of the aabtMacAddr[B2C2_SDK_MAC_ADDR_LIST_MAX][B2C2_SDK_MAC_ADDR_SIZE] array will be listed. In this case, the member 1Count holds the maximum possible number of MAC addresses defined at B2C2_SDK_MAC_ADDR_LIST_MAX and returns the number of MAC addresses set at the aabtMacAddr array. The number of bytes per MAC address in the array is defined at B2C2_SDK_MAC_ADDR_SIZE, which specifies the size of an array member.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

Example

unsigned char curMac[B2C2_SDK_MAC_ADDR_SIZE];

tMacAddressList getMacAddrList;      

memset (&getMacAddrList, 0x00, sizeof (getMacAddrList)); 
getMacAddrList.lCount = B2C2_SDK_MAC_ADDR_LIST_MAX; // Note: Don't forget this line!!!

HRESULT hr = pDataCtrl->GetMulticastMacAddressList (&getMacAddrList);

if (FAILED (hr)) 
{
	// error handling
}
else 
{
	for (int i=0; i < getMacAddrList.lCount; i++)
	{
		memcpy (curMac,
		        getMacAddrList.aabtMacAddr [i], 
		        B2C2_SDK_MAC_ADDR_SIZE);

		// use curMac ... 
	}
}

IB2C2MPEG2DataCtrl3::GetUnicastMacAddress

Return to Top

Gets the current unicast MAC address..

Syntax

HRESULT GetUnicastMacAddress(

unsigned char * pMacAddr

);

Parameters

pMacAddr

[in] Pointer to the array of size B2C2_SDK_MAC_ADDR_SIZE (6 bytes) created by the caller. pMacAddr will hold the current unicast MAC address set at the device.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

Example

unsigned char getMac[B2C2_SDK_MAC_ADDR_SIZE];

HRESULT hr = pDataCtrl->GetUnicastMacAddress (getMac);

if (FAILED (hr)) 
{
	// error handling 
}
else
{
	// use getMac
}

IB2C2MPEG2DataCtrl4::GetHardwareMacAddress

Return to Top

Returns the MAC address of the B2C2 adapter.

Syntax

HRESULT GetHardwareMacAddress(

unsigned char * pHwMacAddr

);

Parameters

pHwMacAddr

[in] Pointer to the array of size B2C2_SDK_MAC_ADDR_SIZE (6 bytes) created by the caller. pHwMacAddr will hold the hardware MAC address of the device.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The hardware MAC address is the MAC address stored at the device's EEPROM. If SetUnicastMacAddress has not been called, the hardware MAC address is equal to the unicast MAC address returned by GetUnicastMacAddress.

RestoreUnicastMacAddress can be used to reset the unicast MAC address with the hardware MAC address returned by GetHardwareMacAddress.

Example

unsigned char getHwMac[B2C2_SDK_MAC_ADDR_SIZE];

HRESULT hr = pDataCtrl->GetHardwareMacAddress (getHwMac);

if (FAILED (hr))
{
	// error handling
}
else
{
	// use getHwMac
}

IB2C2MPEG2DataCtrl3::PurgeGlobalPIDs

Return to Top

Deletes all IP PIDs currently active in the tuner. The current value is 33.

Syntax

HRESULT PurgeGlobalPIDs();

Parameters

None.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

All PIDs are deleted, including those that may not have been created by the current process.


IB2C2MPEG2DataCtrl3::RestoreUnicastMacAddress

Return to Top

Restores the unicast MAC address to the device default.

Syntax

HRESULT RestoreUnicastMacAddress();

Parameters

None.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

Example

HRESULT hr = pDataCtrl->RestoreUnicastMacAddress ();

if (FAILED (hr)) 
{
	// error handling
}

IB2C2MPEG2DataCtrl3::SetUnicastMacAddress

Return to Top

Set the given unicast MAC addresses.

Syntax

HRESULT SetUnicastMacAddress(

unsigned char * pMacAddr

);

Parameters

pMacAddr

[in] Pointer to the array of size B2C2_SDK_MAC_ADDR_SIZE (6 bytes) created by the caller. pMacAddr holds the new unicast MAC address to be set for the device; the currently set unicast MAC address will be overwritten.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

Example

unsigned char setMac[B2C2_SDK_MAC_ADDR_SIZE] = { 0x01, 0x00, 0x5E, 0x01, 0x01, 0x01 };

HRESULT hr = pDataCtrl->SetUnicastMacAddress (setMac);

if (FAILED (hr))
{
	// error handling
}

IB2C2MPEG2DataCtrl4::SetTableId

Return to Top

Sets the datagram table ID.

Syntax

HRESULT SetTableId(

long lTableId

);

Parameters

lTableId

[in] Long variable used to pass the datagram table ID. See Remarks for further information. Possible values are:

Table ID
Use
TABLE_ID_3E
DVB standard; sometimes used for ATSC.
TABLE_ID_3F
ATSC standard.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The datagram table ID is used to parse datagram sections from incoming transport packets in order to recover data such as IP packets from the transport stream. Network type and data format of the sections are identified by table ID. For example, a table ID of 0x3e typically identifies IP data on a DVB network, while a table ID of 0x3f identifies IP data on an ATSC network.

Currently it is only possible to set the table ID on ATSC devices. SetTableId calls on non-ATSC devices will return successful; however, the device setting will not change. For non-ATSC devices that do not support changing the table ID GetTableId will return TABLE_ID_AUTO.

Example

long lInTableId = TABLE_ID_3E;		// or TABLE_ID_3F for ATSC

HRESULT hr = pDataCtrl->SetTableId (lInTableId); 

if (FAILED (hr))
{ 
	// error handling
}

// New datagram table ID set

IB2C2MPEG2DataCtrl4::GetTableId

Return to Top

Gets the datagram table ID.

Syntax

HRESULT GetTableId(

long * plTableId

);

Parameters

pbtTableId

[out] Pointer to a long variable created by the caller. plTableId will hold the current datagram table ID. Possible values are:

Table ID
Use
TABLE_ID_3E
DVB Standard; sometimes used at ATSC too
TABLE_ID_3F
ATSC Standard
TABLE_ID_AUTO
The table ID is handled automatically or non-ATSC device.

 

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

See SetTableId Remarks for further information. TABLE_ID_AUTO will be returned for non-ATSC devices or devices that use a software algorithm to determine the table ID and parse datagram packets out of the transport stream.

Example

long lOutTableId;

HRESULT hr = pDataCtrl->GetTableId (&lOutTableId); 
  
if (FAILED (hr))
{
	// error handling
}

// Use lOutTableId, holding current datagram table ID

 


OTHER METHODS

The following methods may support multiple protocols:


IB2C2MPEG2DataCtrl3::GetBufferPos

Return to Top

(Linux only.) See Linux DDK documentation.


IB2C2MPEG2DataCtrl3::GetDataReceptionStats

Return to Top

(Windows only.) Retrieves Data Reception Statistics.

Syntax

HRESULT GetDataReceptionStats(

long * plIpQuality

long * plTsQuality

);

Parameters

plIpQuality

[out] Pointer to a long variable created by the caller. Variable will hold the ratio of correctly recovered IP packets to total IP packets measured since last call to this function or to ResetDataReceptionStats.

plTsQuality

[out] Pointer to a long variable created by the caller. Variable will hold the ratio of correctly recovered TS (Transport Stream) packets to total TS packets measured since last call to this function or to ResetDataReceptionStats.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

See also

ResetDataReceptionStats


IB2C2MPEG2DataCtrl3::GetReceivedDataIp

Return to Top

Returns count of bytes and IP packets received.

Syntax

HRESULT GetReceivedDataIp(

__int64 * pllDataRcv,

__int64 * pllIpRcv

);

Parameters

pllDataRcv

[out] Pointer to 64-bit variable where the byte count for total IP data received will be stored.

pllIpRcv

[out] Pointer to 64-bit variable where the packet count for total IP packets received will be stored.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2DataCtrl3::Initialize

This function was implemented in previous versions; in the current version it is no longer necessary to call this function.

Return to Top

(Linux only.) Creates connection to Data Control.

Syntax

HRESULT Initialize();

Parameters

None.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2DataCtrl3::ResetDataReceptionStats

Return to Top

(Windows only.) Defines start time for GetDataReceptionStats calculation.

Syntax

HRESULT ResetDataReceptionStats();

Parameters

None.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

See also

GetDataReceptionStats


IB2C2MPEG2DataCtrl3::SetMacAddress

Return to Top

(Linux only.) Sets MAC Address of broadband device.

Syntax

HRESULT SetMacAddress(

char * paMacAddress

);

Parameters

paMacAddress

[in] Pointer to an array of six bytes created by the caller. Array contains the new MAC Address for the broadband device.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2DataCtrl4::GetKeyCount

Return to Top

Determines whether and how many keys in total and of each type can be set.

Syntax

HRESULT GetKeyCount(

long * plTotal,

long * plPidTscKeys,

long * plPidKeys,

long * plGlobalKey

);

Parameters

plTotal

[out] Pointer to a long variable created by the caller. The variable will return the maximum number of keys that can be returned by GetKeysInUse. If the value is not of interest, pass NULL for this argument.

plPidTscKeys

[out] Pointer to a long variable created by the caller. If the value is not of interest, pass NULL for this argument. Possible values returned in plPidTscKeys are:

Value
Use
0
PID-TSC keys are not supported by the device.
> 0
Number of supported PID-TSC keys.

plPidKeys

[out] Pointer to a long variable created by the caller. The variable will return the number of PID-only keys supported by the device (typically one). If the value is not of interest, pass NULL for this argument.

plGlobalKey

[out] Pointer to a long variable created by the caller. The variable will return the number of global keys supported by the device (typically one). If the value is not of interest, pass NULL for this argument.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Possible Error Values
Description
E_FAIL Internal error, capabilities are not accessible.

Remarks

None.

See also

Scrambling Control Methods

GetKeysInUse; AddKey; DeleteKey; PurgeKeys

Example

long lTotalKeys;
long lPidTscKeys;
long lPidKey;
long lGlobalKey;

HRESULT hr = pDataCtrl->GetKeyCount (&lTotalKeys, &lPidTscKeys, &lPidKey, &lGlobalKey); 
  
if (FAILED (hr))
{
	// error handling
}

if (lTotalKeys > 0)
{
	// Use lTotalKeys value for array size in GetKeysInUse () calls
}

if (lPidTscKeys > 0)
{
	// Set up to lPidTscKeys PID-TSC keys
}
else
{
	// PID-TSC keys NOT supported handling
}

if (lPidKey > 0)
{
	// PID-only key supported handling
}
else
{
	// PID-only key NOT supported handling
}

if (lGlobalKey > 0)
{
	// Global key supported handling
}
else
{
	// Global key NOT supported handling
}

IB2C2MPEG2DataCtrl4::GetKeysInUse

Return to Top

Gets a list of key types and PIDs for which keys are currently set.

Syntax

HRESULT GetKeysInUse(

long * plCount,

long * plTypeArray,

long * plPidArray

);

Parameters

plCount

[in/out] Pointer to a long variable created by the caller. The input for plCount is the number of fields in the arrays for the second and third arguments (plPidArray and plTypeArray). Typically the input value is equal to the value returned by the first argument (plTotal) of GetKeyCount. The output value is the number of Type/PID value-pairs set in the second and third argument.

plTypeArray

[out] Pointer to a array of long variables created by the caller. The size of this array must be given in the first argument (plCount). plTypeArray will contain the type for current keys. The number of array fields updated will be returned by value of plCount. See Scrambling Control Methods for further details. Possible values are:

Type Value
Description
PID-TSC keys
B2C2_KEY_PID_TSC_01
Key is used if the PID matches and the TSC bits are '01' (reserved).
B2C2_KEY_PID_TSC_10
Key is used if the PID matches and the TSC bits are '10' (even).
B2C2_KEY_PID_TSC_11
Key is used if the PID matches and the TSC bits are '11' (odd).
PID-only key
B2C2_KEY_PID_TSC_ANY
Key is used if no B2C2_KEY_PID_TSC_XX key and the PID value matches.
Global Key
B2C2_KEY_GLOBAL
Key is used if no B2C2_KEY_PID_TSC_XX key matches.

plPidArray

[out] Pointer to a array of long variables created by the caller. The size of this array must be given in the first argument (plCount). plPidArray will contain the PIDs for current keys. The number of array fields updated will be returned in plCount. If the key type is B2C2_KEY_GLOBAL the value of the corresponding plPidArray field has no meaning.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Possible Error Values
Description
E_POINTER plCount, plPidArray or plTypeArray is not a valid pointer value (= NULL).
E_FAIL Internal error, driver or capabilities are not accessible..
B2C2_SDK_E_GET_PID_FIXED_KEYS

Attempt to get the currently set keys failed; a possible reason can be that the current device does not support keys.

Remarks

None.

See also

Scrambling Control Methods

GetKeyCount; AddKey; DeleteKey; PurgeKeys

Example

long lTotalKeys;

HRESULT hr = pDataCtrl->GetKeyCount (&lTotalKeys, NULL, NULL, NULL); 
  
if (FAILED (hr))
{
	// GetKeyCount error handling
	return;
}
			
long lKeys = lTotalKeys;
long *palPids = new long[lTotalKeys];
long *palType = new long[lTotalKeys];

hr = pDataCtrl->GetKeysInUse (&lKeys, palType, palPids);

if (   SUCCEEDED(hr)
    && lKeys > 0)
{
	for (long lCnt = 0; lCnt < lKeys; lCnt++)
	{
		switch (palType[lCnt])
		{
		// PID TSC keys 
		case B2C2_KEY_PID_TSC_01 :	// reserved
		case B2C2_KEY_PID_TSC_10 :	// even
		case B2C2_KEY_PID_TSC_11 :	// odd
			// palPids[lCnt] contains PID; TSC value is '01', '10' or '11'
			break;
		// PID Key
		case B2C2_KEY_PID_TSC_ANY :
			// palPids[lCnt] contains PID
			break;
		// Global Key 
		case B2C2_KEY_GLOBAL :
			// Global key is set
			break;
		}
	}
}

delete [] palPids;
delete [] palType;

if (FAILED (hr))
{
	// GetKeysInUse error handling
}

IB2C2MPEG2DataCtrl4::AddKey

Return to Top

Adds a key for decrypting packets.

Syntax

HRESULT AddPidKey(

long lType,

long lPid,

unsigned char * pKey,

long lKeyLength

);

Parameters

lType

[in] Type of key to be set. See Scrambling Control Methods for further details. Possible values are:

Type Value
Description
PID-TSC keys
B2C2_KEY_PID_TSC_01
Key is used if the PID matches and the TSC bits are '01' (reserved).
B2C2_KEY_PID_TSC_10
Key is used if the PID matches and the TSC bits are '10' (even).
B2C2_KEY_PID_TSC_11
Key is used if the PID matches and the TSC bits are '11' (odd).
PID-only key
B2C2_KEY_PID_TSC_ANY
Key is used if no B2C2_KEY_PID_TSC_XX key matches and the PID value matches.
Global Key
B2C2_KEY_GLOBAL
Key is used if no B2C2_KEY_PID_TSC_XX key matches.

lPid

[in] PID for which the key shall be used. lPid is ignored if the type value is B2C2_KEY_GLOBAL.

pKey

[in] Pointer to an array of bytes holding the key.

lKeyLength

[in] Length of the array pointed to by pKey (in bytes). For current devices this lKeyLength must be B2C2_SDK_FIXED_KEY_SIZE (8 bytes).

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Possible Error Values
Description
E_POINTER pKey is not a valid pointer value (= NULL).
E_INVALIDARG The lTsc value or the key length given by lKeyLength is invalid.
E_FAIL Internal error, driver is not accessible.
B2C2_SDK_E_SET_PID_FIXED_KEY

If attempting to set the B2C2_KEY_PID_TSC_XX key failed, possible reasons could be:
- the maximum number of PID-TSC keys are set
- or the current device does not support PID-TSC keys.

If attempting to set the B2C2_KEY_PID_TSC_ANY key failed, possible reasons could be:
- the
B2C2_KEY_GLOBAL global key is set
- or the current device does not support PID-only key.

B2C2_SDK_E_SET_GLOBAL_FIXED_KEY

If attempting to set the global key (B2C2_KEY_GLOBAL) failed; possible reasons are:
- the
B2C2_KEY_PID_TSC_ANY key is set
- or the current device does not support a global key.

Remarks

Adding a PID key will not automatically add the PID to the receiver. Data can only be received after the PID is added by calling one of the functions AddIpPIDs, AddTsPIDs (Linux), AddPIDsToPin (Windows) or IB2C2MPEG2AVCtrl::SetAudioVideoPIDs depending on the stream type.

See also

Scrambling Control Methods

GetKeyCount; GetKeysInUse; DeleteKey; PurgeKeys


IB2C2MPEG2DataCtrl4::DeleteKey

Return to Top

Delete key for decrypting packets.

Syntax

HRESULT DeleteKey(

long lType,

long lPid

);

Parameters

lType

[in] Type of the key to be deleted. See Scrambling Control Methods for further details. Possible values are:

Type Value
Description
PID-TSC keys
B2C2_KEY_PID_TSC_01
Key is used if the PID matches and the TSC bits are '01' (reserved).
B2C2_KEY_PID_TSC_10
Key is used if the PID matches and the TSC bits are '10' (even).
B2C2_KEY_PID_TSC_11
Key is used if the PID matches and the TSC bits are '11' (odd).
PID-only key
B2C2_KEY_PID_TSC_ANY
Key is used if no B2C2_KEY_PID_TSC_XX key matches and the PID value matches.
Global Key
B2C2_KEY_GLOBAL
Key is used if no B2C2_KEY_PID_TSC_XX key matches.

lPid

[in] PID for which the key shall be deleted. lPid is ignored if the type value is B2C2_KEY_GLOBAL or B2C2_KEY_PID_TSC_ANY (e.g. it is not necessary to specify the PID if deleting the Global or PID-only key).

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Possible Error Values
Description
E_INVALIDARG The lTsc value is invalid.
E_FAIL Internal error, driver is not accessible.
B2C2_SDK_E_DELETE_PID_FIXED_KEY

Attempt to delete a B2C2_KEY_PID_TSC_XX key failed; possible reasons are:
- the key specified by type and PID is not set
- or the current device does not support PID keys.

B2C2_SDK_E_SET_PID_FIXED_KEY Attempt to delete a B2C2_KEY_PID_TSC_ANY key failed; possible reasons are:
- the
B2C2_KEY_PID_TSC_ANY key is not set
- or the current device does not support
B2C2_KEY_PID_TSC_ANY key.
B2C2_SDK_E_SET_GLOBAL_FIXED_KEY Attempt to delete a B2C2_KEY_GLOBAL key failed; possible reasons are:
- the
B2C2_KEY_GLOBALkey is not set
- or the current device does not support
B2C2_KEY_GLOBAL key.

Remarks

None.

See also

Scrambling Control Methods

GetKeyCount; GetKeysInUse; AddKey; PurgeKeys


IB2C2MPEG2DataCtrl4::PurgeKeys

Return to Top

Delete all keys currently set.

Syntax

HRESULT PurgeKeys();

Parameters

None.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Possible Error Values
Description
E_FAIL Internal error, driver is not accessible.
B2C2_SDK_E_PURGE_FIXED_KEY

Attempt to purge the keys failed; a possible reason can be that the current device does not support keys.

Remarks

None.

See also

Scrambling Control Methods

GetKeyCount; GetKeysInUse; AddKey; DeleteKey


Copyright © 1998-2002 B2C2, Inc. Proprietary and Confidential