B2C2, Inc. - Software Development Kit |
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.
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: |
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. |
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.
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 |
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 |
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 |
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 |
The following methods are for use with the Transport Stream protocols:
The AddPIDs function is obsolete and is implemented for backwards compatibility only. Current version uses AddPIDsToPin (Windows) or AddTsPIDs (Linux) method.
(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
(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
(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
The DeletePIDs function is obsolete and is implemented for backwards compatibility only. Current version uses DeletePIDsFromPin (Windows) or DeleteTsPIDs (Linux) method.
(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
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 }
(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
(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
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.
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.
The following methods are for use with Internet Protocol (IP) packets.
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 }
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
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
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
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
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.
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.
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.
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 ... } }
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 }
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 }
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.
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 }
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 }
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_3EDVB standard; sometimes used for ATSC. TABLE_ID_3FATSC standard.
Return Value
Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.
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
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_3EDVB Standard; sometimes used at ATSC too TABLE_ID_3FATSC Standard TABLE_ID_AUTOThe 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
The following methods may support multiple protocols:
(Linux only.) See Linux DDK documentation.
(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
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.
This function was implemented in previous versions; in the current version it is no longer necessary to call this function.
(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.
(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
(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.
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 0PID-TSC keys are not supported by the device. > 0Number 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 DescriptionE_FAIL Internal error, capabilities are not accessible.
Remarks
None.
See also
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 }
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_01Key is used if the PID matches and the TSC bits are '01' (reserved). B2C2_KEY_PID_TSC_10Key is used if the PID matches and the TSC bits are '10' (even). B2C2_KEY_PID_TSC_11Key is used if the PID matches and the TSC bits are '11' (odd). PID-only key B2C2_KEY_PID_TSC_ANYKey is used if no B2C2_KEY_PID_TSC_XX key and the PID value matches. Global Key B2C2_KEY_GLOBALKey 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 DescriptionE_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
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 }
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_01Key is used if the PID matches and the TSC bits are '01' (reserved). B2C2_KEY_PID_TSC_10Key is used if the PID matches and the TSC bits are '10' (even). B2C2_KEY_PID_TSC_11Key is used if the PID matches and the TSC bits are '11' (odd). PID-only key B2C2_KEY_PID_TSC_ANYKey is used if no B2C2_KEY_PID_TSC_XX key matches and the PID value matches. Global Key B2C2_KEY_GLOBALKey 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 DescriptionE_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.
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
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_01Key is used if the PID matches and the TSC bits are '01' (reserved). B2C2_KEY_PID_TSC_10Key is used if the PID matches and the TSC bits are '10' (even). B2C2_KEY_PID_TSC_11Key is used if the PID matches and the TSC bits are '11' (odd). PID-only key B2C2_KEY_PID_TSC_ANYKey is used if no B2C2_KEY_PID_TSC_XX key matches and the PID value matches. Global Key B2C2_KEY_GLOBALKey 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 DescriptionE_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
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 DescriptionE_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