SFBQoSBundle

Wrapper Class for the IQoSBundle interface.

#include <SFBQoSBundle.h.hpp>

class SFBQoSBundle : public SFBQuery;

SFMTYPEDEFWRAPPER(SFBQoSBundle)

Inheritance diagram

Version

BREW 2.0	BREW 2.1	BREW 3.1	BREW 4.0
X	X	O	O

Reference

BREW API IQoSBundle

Member

Public Functions
`SFCError`	AddRetryCB( `AEECallback *` retry ) This function should be used by clients in order to be notified when the Open() operation should be retried.
`SFCError`	Close( `SFBQoSListSmpConstRef` sessions ) This function issues a request for closing multiple QoS Sessions. The request is forwarded to lower layers in order to release the QoS links resources.
`SFCError`	Deactivate( `SFBQoSListSmpConstRef` sessions ) This function is used in order to suspend multiple QoS links.
`SFCError`	GetError( `AEEQoSSessionError *` error ) This function returns an AEEQoSSessionError that can be used by clients in order to receive information on the reason for the failure.
`SFCError`	GoActive( `SFBQoSListSmpConstRef` sessions ) This function is used in order to activate multiple QoS links.
static `SFBQoSBundleSmp`	NewInstance( `SFCErrorPtr` exception = null ) Create a new SFBQoSBundle instance.
static `SFBQoSBundleSmp`	NewInstance( `AEECLSID` id , `SFCErrorPtr` exception = null ) Create a new SFBQoSBundle instance.
`SFCError`	Open( `SFBQoSListSmpConstRef` sessions , `SFBQoSListSmpConstRef` specs ) This function issues request for establishing new multiple QoS Sessions linked to the same data network and expects the QoS Sessions to be granted immediately.
`SFCError`	SelectNetworkEx( `SInt32` network , `SInt16` family ) This function selects a specific data network to be associated with the QoS Bundle.
`SFCError`	QueryInterface( `AEECLSID` clsid , `VoidHandle` handle ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`SFCError`	QueryInterface( `AEECLSID` clsid , `SFBBaseSmpPtr` handle ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`SFBBaseSmp`	QueryInterface( `AEECLSID` clsid ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`Void`	Self( `AEECLSID` clsidReq , `SFBQuerySmpPtr` clone , `AEECLSID` clsidImp ) (inherits from SFBQuery) Helper macro for those implementing an object with a single interface.
`SFBQuerySmp`	Self( `AEECLSID` clsidReq , `AEECLSID` clsidImp ) (inherits from SFBQuery) Helper macro for those implementing an object with a single interface.

Protected Functions
static `SFBBaseSmp`	FactoryByCreate( `AEECLSID` id , `SFCErrorPtr` exception = null ) (inherits from SFBBase) Create the instance for the specified ClassID's interface.
static `SFBBaseSmp`	FactoryByQuery( `SFBQuerySmpConstRef` query , `AEECLSID` id , `SFCErrorPtr` exception = null ) (inherits from SFBBase) Create the instance for the specified ClassID's interface using the SFBQuery instance.

SFBQoSBundle::AddRetryCB

This function should be used by clients in order to be notified when the Open() operation should be retried.

[ public ]
SFCError AddRetryCB(
    AEECallback * retry   // the client's callback
);

Return value

AEE_SUCCESS: client's callback was stored successfully.
AEE_EBADSTATE: QoSBundle state is not suitable for this operation.
AEE_EBADPARM: client's callback is invalid.

Other error codes are also possible

Description

In the case where SFBQoSBundle::Open() returns AEE_NET_WOULDBLOCK, SFBQoSBundle::Open() should be called again later to obtain the final result (error or success).

For notification of when to call SFBQoSBundle::Open() again, the client should register a callback through SFBQoSBundle::AddRetryCB().

Note that when the client's callback is resumed, it is not guaranteed that a subsequent call to SFBQoSBundle::Open() will complete, so the client must be prepared to receive AEE_NET_WOULDBLOCK again.

Reference

BREW API IQoSBundle_AddRetryCB

SFBQoSBundle::Close

This function issues a request for closing multiple QoS Sessions. The request is forwarded to lower layers in order to release the QoS links resources.

[ public ]
SFCError Close(
    SFBQoSListSmpConstRef sessions   // list of valid QoS sessions to be released
);

Return value

AEE_NET_SUCCESS: the request was successfully issued. This doesn't indicate that all QoS resources are released yet.
AEE_EBADPARM: the QoS Session list is invalid.
AEE_NET_EQOS_NET_CONFLICT: conflict between the QoS Session's networks.
AEE_NET_EQOS_SESSION_INVALID_OPT: at least one of the QoS Session in the list is invalid or prevented the Close operation from ending successfully e.g. the QoSSession state is not suitable for this operation, Use SFBQoSBundle::GetError() to identify the index to the first QoS Session in the list which caused the failure and to reveal the error code (See AEEQoSSessionError).
AEE_EBADSTATE: QoSSession state is not suitable for this operation.
AEE_ENOMEMORY: out of memory.

Other error codes are also possible.

Description

The number of requested QoS Sessions in a bundle is limited and cannot exceed MAX_UINT8.

All QoS Sessions which are requested to be closed must be linked to the same network, otherwise the operation will fail and none of the QoS Session instances will be released.

In addition all QoS Sessions which are requested to be closed must be closeable, otherwise the operation will fail and none of the QoS Session instances will be released.

Note that a return value of AEE_SUCCESS indicates that the request was successfully issued but it doesn't indicate that all QoS Sessions are released.

After SFBQoSBundle::Close() returns AEE_SUCCESS, the client should listen (see IQoSSession_AddListener()) for QoS events, separately for each QoS Session, which indicate that QoS was released (AEE_QOS_UNAVAILABLE_EV).

After calling IQoSBundle_Close(), the QoS Bundle object can be re-used for any other multiple session operations with any bundle of SFBQoSSession objects.

Reference

BREW API IQoSBundle_Close

SFBQoSBundle::Deactivate

This function is used in order to suspend multiple QoS links.

[ public ]
SFCError Deactivate(
    SFBQoSListSmpConstRef sessions   // list of valid QoS sessions to be suspended. 
);

Return value

AEE_SUCCESS: the request was successfully issued. This doesn't indicate that the QoS Sessions are already suspended.
AEE_EBADPARM: the QoS Session list is invalid.
AEE_NET_EQOS_NET_CONFLICT: conflict between the QoS Session's networks.
AEE_NET_EQOS_SESSION_INVALID_OPT: at least one of the QoS Session in the list is invalid or prevented the Deactivate operation from ending successfully e.g. the QoSSession state is not suitable for this operation, Use SFBQoSBundle::GetError() to identify the index to the first QoS Session in the list which caused the failure and to reveal the error code (See AEEQoSSessionError).
AEE_NET_EQOSUNAWARE : the current network is CDMA QoS Unaware System (does not support QoS).
EAEE_NOMEMORY: out of memory.

Other error codes are also possible.

Description

The number of requested QoS Sessions in a bundle is limited and cannot exceed MAX_UINT8.

All QoS Sessions which are requested to be suspended must be linked to the same network, otherwise the operation will fail and none of the QoS Session instances will be suspended.

In addition all QoS Sessions which are requested to be suspended must be in a state which enables suspension, otherwise the operation will fail and none of the QoS Session instances will be suspended.

Note that a return value of AEE_SUCCESS indicates that the request was successfully issued but it doesn't indicate that the QoS Sessions are already suspended. After IQoSBundle_Deactivate() returns AEE_SUCCESS, the client should listen (see SFBQoSSession::AddListener()) for QoS events, separately for each QoS Session, which indicate that QoS was suspended (DSS_IFACE_IOCTL_QOS_AVAILABLE_DEACTIVATED_EV).

After calling SFBQoSBundle::Deactivate(), the QoS Bundle object can be re-used for any other multiple session operations with any bundle of IQoSSession objects.

Reference

BREW API IQoSBundle_Deactivate

SFBQoSBundle::GetError

This function returns an AEEQoSSessionError that can be used by clients in order to receive information on the reason for the failure.

[ public ]
SFCError GetError(
    AEEQoSSessionError * error   // returns a QoS Session error
);

Return value

AEE_SUCCESS: error was successfully retrieved into pError.
AEE_EBADPARM: the provided pError parameter is invalid.

Description

Clients should call this function after a QoS Bundle operation ( SFBQoSBundle::Open(), SFBQoSBundle::Close(), SFBQoSBundle::GoActive(), SFBQoSBundle::Deactivate()) returns AEE_NET_EQOS_SESSION_INVALID_OPT.

In this case the AEEQoSSessionError will indicate which QoS Session in the bundle caused the failure and what was the type of the error.

In case the returned error code is AEE_QOS_SESSION_ERR_CODE_INVAL_SPEC the client can refer to the appropriate QoS Session in the QoS Sessions list (according to the AEEQoSSessionError index value) and call SFBQoSSession::GetError() to receive more information on the QoS Specification error. 1

Reference

BREW API IQoSBundle_GetError

SFBQoSBundle::GoActive

This function is used in order to activate multiple QoS links.

[ public ]
SFCError GoActive(
    SFBQoSListSmpConstRef sessions   // list of valid QoS sessions to be activated. 
);

Return value

AEE_SUCCESS: the request was successfully issued. This doesn't indicate that the QoS Sessions are already available.
AEE_EBADPARM: the QoS Session list is invalid.
AEE_NET_EQOS_NET_CONFLICT: conflict between the QoS Session's networks.
AEE_NET_EQOS_SESSION_INVALID_OPT: at least one of the QoS Session in the list is invalid or prevented the Activate operation from ending successfully e.g. the QoSSession state is not suitable for this operation. Use SFBQoSBundle::GetError() to identify the index to the first QoS Session in the list which caused the failure and to reveal the error code (See AEEQoSSessionError).
AEE_NET_EQOSUNAWARE : the current network is CDMA QoS Unaware System (does not support QoS).
AEE_ENOMEMORY: out of memory.

Other error codes are also possible.

Description

The number of requested QoS Sessions in a bundle is limited and cannot exceed MAX_UINT8.

All QoS Sessions which are requested to be activated must be linked to the same network, otherwise the operation will fail and none of the QoS Session instances will be activated.

In addition all QoS Sessions which are requested to be activated must be in a state which enables activation, otherwise the operation will fail and none of the QoS Session instances will be activated.

ANote that a return value of AEE_SUCCESS indicates that the request was successfully issued but it doesn't indicate that the QoS Sessions are already active. After IQoSBundle_GoActive() returns AEE_SUCCESS, the client should listen (see SFBQoSSession::AddListener()) for QoS events, separately for each QoS Session, which indicate that QoS was activated (AEE_QOS_AVAILABLE_MODIFIED_EV).

After calling SFBQoSBundle_GoActive(), the QoS Bundle object can be re-used for any other multiple session operations with any bundle of SFBQoSSession objects.

Reference

BREW API IQoSBundle_GoActive

SFBQoSBundle::NewInstance

Create a new SFBQoSBundle instance.

[ public, static ]
SFBQoSBundleSmp NewInstance(
    SFCErrorPtr exception = null   // Error
);

[ public, static ]
SFBQoSBundleSmp NewInstance(
    AEECLSID id                    // Class ID
    SFCErrorPtr exception = null   // Error
);

SFBQoSBundle::Open

This function issues request for establishing new multiple QoS Sessions linked to the same data network and expects the QoS Sessions to be granted immediately.

[ public ]
SFCError Open(
    SFBQoSListSmpConstRef sessions   // list of requested QoS sessions
    SFBQoSListSmpConstRef specs      // list of desired QoS specification for the new sessions
);

Return value

AEE_SUCCESS: the request was successfully issued. This doesn't indicate that the QoS Sessions are already available.
AEE_NET_WOULDBLOCK: operation cannot be completed right now; use SFBQoSBundle_AddRetryCB() to try again later.
AEE_EBADPARM: the QoS Session list or QoS Spec list are invalid, or are not of the same length.
AEE_NET_EQOS_SESSION_INVALID_OPT: at least one of the QoS Session in the list is invalid or prevented the Open operation from ending successfully e.g. the QoSSession state is not suitable for this operation, the QoSSession's network does not match the QoS Bundle's network, the QoS Specification is invalid etc. Use SFBQoSBundle_GetError() to identify the index to the first QoS Session in the list which caused the failure and to reveal the error code (See AEEQoSSessionError).
AEE_NET_EQOSUNAWARE : the current network is CDMA QoS Unaware System (does not support QoS).
AEE_ENOMEMORY: out of memory.

Other error codes are also possible.

Description

The number of requested QoS Sessions in a bundle is limited and cannot exceed MAX_UINT8.

The QoS Bundle's network will be used as the data network for all the QoS Sessions in the bundle. Each requested QoS Session in the bundle, must either specify a network which is identical to the bundle's network or not specify a network at all.

In any other case the operation will fail and none of the QoS Sessions will be established. Upon an AEE_SUCCESS Open request, all QoS Sessions within the bundle will be associated to the same data network as the bundle.

If a network was not yet selected for the IQoSBundle instance (SFBQoSBundle..SelectNetworkEx()), AEE_NETWORK_DEFAULT will be implicitly selected.

Reference

BREW API IQoSBundle_Open

SFBQoSBundle::SelectNetworkEx

This function selects a specific data network to be associated with the QoS Bundle.

[ public ]
SFCError SelectNetworkEx(
    SInt32 network   // data network type (AEE_NETWORK_*) 
    SInt16 family    // address family (AEE_AF_*) 
);

Return value

AEE_SUCCESS: the data network was selected.
AEE_NET_EINVAL: the network is not valid.
AEE_EBADSTATE: the operation is currently not applicable.
AEE_EFAILED: other failure.

Other error codes are also possible.

Description

Each QoS Session is associated to a data network. IQoSBundle_SelectNetworkEx() will not change the QoS Sessions' data network.

Upon SFBQoSBundle_Open(), each QoS Session within the bundle must either be associated to a data network which is identical to the bundle's selected network, or not specify a network at all. Otherwise the Open request will fail.

When an SFBQoSBundle instance is created, no network is selected. If SFBQoSBundle::Open() is called before SFBQoSBundle::SelectNetworkEx(), AEE_NETWORK_DEFAULT will be implicitly selected.

The SFBQoSBundle instance is re-usable, therefor the client may call SFBQoSBundle::SelectNetworkEx() multiple times on the same bundle instance.

Reference

BREW API IQoSBundle_SelectNetworkEx