CSenXmlServiceDescription Class Reference

API published in: S60 3rd Ed

Link against: senservdesc.lib

Capability Information

Required Capabilities

NetworkServices ReadUserData WriteUserData

#include <senxmlservicedescription.h>

Inherits CSenDomFragment, MSenServiceDescription, and MSenProviderPolicy.

Inherited by CSenIdentityProvider, and CSenServicePattern.

Detailed Description

CSenXmlServiceDescription class implements the most common value object used in WSF, which is used to describe some invocable service.

Class offers basic properties which describe some service and methods to manipulate this info. These properties are stored in XML fragment format and a class instance can be represented as one XML tree.

The main properties for service description are:

contract (typically some URI)
endpoint (typically some URL)
frameworkID


Public Member Functions
virtual IMPORT_C	~CSenXmlServiceDescription ()
	Destructor.
IMPORT_C void	SetFrameworkIdL (const TDesC8 &aFrameworkID)
	Setter for the framework ID.
virtual IMPORT_C const TDesC8 &	NewElementName ()
	Method returns the localname for this service description.
IMPORT_C RCredentialList &	Credentials ()
	Returns list of credentials.
virtual IMPORT_C void	SetIapIdL (TUint32 aIapId)
	Setter for Internet Access Point (IAP) ID.
virtual IMPORT_C TInt	IapId (TUint32 &aCurrentIapId)
	Getter for IAP ID.
virtual IMPORT_C void	SetIdentityProviderIdsL (CSenIdentityProviderIdArray8 &aList)
	Setter for IdentityProvider IDs.
virtual IMPORT_C TInt	AddIdentityProviderIdL (TDesC8 &aProviderId)
	Adds a new IdentityProviderID value at the end of the current list values.
virtual IMPORT_C TInt	RebuildFrom (MSenProviderPolicy &aTemplate)
	Method reads provider policy class instance values from given template.
virtual IMPORT_C const CSenIdentityProviderIdArray8 &	IdentityProviderIds8L ()
	Getter for IdentityProvider IDs.
virtual IMPORT_C TBool	Accepts (MSenProviderPolicy &aPolicyPattern)
	Checks if some policy is accepted by current policy.
IMPORT_C TDescriptionClassType	DescriptionClassType ()
	The DescriptionClassType() method is used to resolve the real subclass type in cases where instance of that class is seen through one of its superclass interfaces.
IMPORT_C TBool	Matches (MSenServiceDescription &aPattern)
	Method returns ETrue if this service description matches the given pattern.
IMPORT_C TPtrC8	Contract ()
	Getter for contract, which is typically some URI.
virtual IMPORT_C TInt	HasFacetL (const TDesC8 &aURI, TBool &aHasFacet)
	Method for checking if service description has a certain facet.
virtual IMPORT_C TInt	FacetValue (TDesC8 &aURI, HBufC8 *&aValueTo)
virtual IMPORT_C TInt	AddFacetL (const CSenFacet &aFacet)
	Method for adding a facet.
virtual IMPORT_C TInt	SetFacetL (const CSenFacet &aFacet)
	Method for setting a facet.Adds a new facet, if non-existent.
virtual IMPORT_C TInt	RemoveFacet (const TDesC8 &aURI)
	Removes a characteristic (Facet) from the description.
virtual IMPORT_C TInt	FacetsL (RFacetArray &aFacetArray)
	Method for getting all facets.
virtual IMPORT_C TInt	ScoreMatchL (MSenServiceDescription &aPattern)
	Method returns a positive integer if this ServiceDescription matches the given pattern in at least one aspect.
IMPORT_C TPtrC8	Endpoint ()
	Getter for endpoint.
IMPORT_C TPtrC8	FrameworkId ()
	Getter for the framework ID.
IMPORT_C TPtrC8	FrameworkVersion ()
	Getter for the framework version.
IMPORT_C void	SetContractL (const TDesC8 &aContract)
	Setter for contract.
IMPORT_C void	SetEndPointL (const TDesC8 &aEndPoint)
	Setter for endpoint.
virtual IMPORT_C HBufC8 *	AsXmlL ()
	Gets the service description as XML fragment in UTF-8 format.
virtual IMPORT_C HBufC *	AsXmlUnicodeL ()
	Gets the service description as XML, in Unicode (UCS-2).
virtual IMPORT_C void	WriteAsXMLToL (RWriteStream &aWriteStream)
	Writes this service description as XML, in UTF-8 form to a stream.
IMPORT_C void	SetAttributesL (const RAttributeArray &aAttributes)
	Method looks for FrameworkID attribute from the given XML attribute array and if one is found, sets its value for this instance.
IMPORT_C void	ResumeParsingFromL (const TDesC8 &aNsUri, const TDesC8 &aLocalName, const TDesC8 &aQName)
	Resumes the parsing.
Static Public Member Functions
static IMPORT_C CSenXmlServiceDescription *	NewL ()
	Standard 2 phase constructor.
static IMPORT_C CSenXmlServiceDescription *	NewLC ()
	Standard 2 phase constructor.
static IMPORT_C CSenXmlServiceDescription *	NewL (const TDesC8 &aNamespaceURI)
	Standard 2 phase constructor.
static IMPORT_C CSenXmlServiceDescription *	NewLC (const TDesC8 &aNamespaceURI)
	Standard 2 phase constructor.
static IMPORT_C CSenXmlServiceDescription *	NewL (const TDesC8 &aEndPoint, const TDesC8 &aContract)
	Standard 2 phase constructors.
static IMPORT_C CSenXmlServiceDescription *	NewLC (const TDesC8 &aEndPoint, const TDesC8 &aContract)
	Standard 2 phase constructors.
Protected Member Functions
IMPORT_C	CSenXmlServiceDescription (TDescriptionClassType aType)
	C++ default constructor.
IMPORT_C void	ConstructL ()
	Basic ConstructL function.
IMPORT_C void	ConstructL (const TDesC8 &aNamespaceURI)
	Basic ConstructL function.
IMPORT_C void	ConstructL (const TDesC8 &aEndPoint, const TDesC8 &aContract)
	Basic ConstructL function.
virtual IMPORT_C void	StartElementL (const TDesC8 &aNsUri, const TDesC8 &aLocalName, const TDesC8 &aQName, const RAttributeArray &aAttributes)
	Callback function which implements the XML content handler interface.
virtual IMPORT_C void	EndElementL (const TDesC8 &aNsUri, const TDesC8 &aLocalName, const TDesC8 &aQName)
	Callback function which implement the XML content handler interface.
Protected Attributes
const TDescriptionClassType	iType

Constructor & Destructor Documentation

virtual IMPORT_C CSenXmlServiceDescription::~CSenXmlServiceDescription ( ) [virtual]

Destructor.

IMPORT_C CSenXmlServiceDescription::CSenXmlServiceDescription ( TDescriptionClassType aType ) [protected]

C++ default constructor.

Parameters:

aType

enumeration defining the type of this class.

Member Function Documentation

virtual IMPORT_C TBool CSenXmlServiceDescription::Accepts ( MSenProviderPolicy & aPolicyPattern ) [virtual]

Checks if some policy is accepted by current policy.

Parameters:

aPolicyPattern

is the policy being compared with this instance.

Returns:: ETrue if policy candidate is accepted by current policy definition, EFalse if not.

Implements MSenProviderPolicy.

virtual IMPORT_C TInt CSenXmlServiceDescription::AddFacetL ( const CSenFacet & aFacet ) [virtual]

Method for adding a facet.

Will NOT override an already existing facet with a same name.

Parameters:

aFacet

is the one to be added. A copy of the the original facet instance will be added.

Returns:: KErrNone or other system-wide Symbian error codes. KErrAlreadyExists if a facet with same name exists

Implements MSenServiceDescription.

virtual IMPORT_C TInt CSenXmlServiceDescription::AddIdentityProviderIdL ( TDesC8 & aProviderId ) [virtual]

Adds a new IdentityProviderID value at the end of the current list values.

Parameters:

aProviderID

defines, which IdentityProvider is preferred OR which is strictly acceptable one, when initiating a new service connection.

Returns:: KErrAlreadyExists, if a duplicate is tried to add KErrArgument if a zero-length descriptor is tried to add (aProviderId.Length() == 0)

Implements MSenProviderPolicy.

virtual IMPORT_C HBufC8* CSenXmlServiceDescription::AsXmlL ( ) [virtual]

Gets the service description as XML fragment in UTF-8 format.

Returns:: the service description as XML, which ownership is transferred to the caller.

Implements MSenServiceDescription.

virtual IMPORT_C HBufC* CSenXmlServiceDescription::AsXmlUnicodeL ( ) [virtual]

Gets the service description as XML, in Unicode (UCS-2).

Returns:: the service description as XML, which ownership is transferred to the caller.

Implements MSenServiceDescription.

IMPORT_C void CSenXmlServiceDescription::ConstructL	(	const TDesC8 &	aEndPoint,
		const TDesC8 &	aContract
	)	`[protected]`

Basic ConstructL function.

Parameters:

	aEndpoint	the service endpoint. Note that endpoint cannot include characters which are illegal in XML. If endpoint is an URL which contains illegal characters (like '&'-char), those need to be encoded into XML entity form (like &). EncodeHttpCharactersLC() method from XmlUtils can be used for encoding of basic XML entities.
	aContract	identifies the service type, typically some URN.

Reimplemented in CSenIdentityProvider.

IMPORT_C void CSenXmlServiceDescription::ConstructL ( const TDesC8 & aNamespaceURI ) [protected]

Basic ConstructL function.

Parameters:

aNamespaceURI

for this service description, which is also an XML element.

Reimplemented in CSenIdentityProvider.

IMPORT_C void CSenXmlServiceDescription::ConstructL ( ) [protected]

Basic ConstructL function.

IMPORT_C TPtrC8 CSenXmlServiceDescription::Contract ( ) [virtual]

Getter for contract, which is typically some URI.

Returns:: the Contract

Implements MSenServiceDescription.

IMPORT_C RCredentialList& CSenXmlServiceDescription::Credentials

(

)

Returns list of credentials.

Ownership is not transferred, any modifications to the contents of the list modify the real objects.

Returns:: the list of credentials (CSenCredential objects).

IMPORT_C TDescriptionClassType CSenXmlServiceDescription::DescriptionClassType ( ) [virtual]

The DescriptionClassType() method is used to resolve the real subclass type in cases where instance of that class is seen through one of its superclass interfaces.

Returns:: TDescriptionClassType enumeration identifying the class.

Implements MSenServiceDescription.

virtual IMPORT_C void CSenXmlServiceDescription::EndElementL	(	const TDesC8 &	aNsUri,
		const TDesC8 &	aLocalName,
		const TDesC8 &	aQName
	)	`[protected, virtual]`

Callback function which implement the XML content handler interface.

Parameters:

	aNsUri	The namespace URI of the new element
	aLocalName	The local name of the new element
	aQName	The qualified name of the new element

Reimplemented from CSenBaseFragment.

IMPORT_C TPtrC8 CSenXmlServiceDescription::Endpoint ( ) [virtual]

Getter for endpoint.

Returns:: The endpoint.

Implements MSenServiceDescription.

virtual IMPORT_C TInt CSenXmlServiceDescription::FacetsL ( RFacetArray & aFacetArray ) [virtual]

Method for getting all facets.

Copies characteristics (Facets) from the description into array. For each characteristic (Facet) found in array the HasFacetL() method should return "ETrue".

Parameters:

aFacetArray

is typically an empty array, into where copies of facets will be added. Ownership of the items in this array is transferred to the caller.

Returns:: KErrNone or other system-wide Symbian error codes.

Implements MSenServiceDescription.

virtual IMPORT_C TInt CSenXmlServiceDescription::FacetValue	(	TDesC8 &	aURI,
		HBufC8 *&	aValueTo
	)	`[virtual]`

Implements MSenServiceDescription.

IMPORT_C TPtrC8 CSenXmlServiceDescription::FrameworkId ( ) [virtual]

Getter for the framework ID.

Returns:: The framework ID or KNullDesC8 if no framework is set

Implements MSenServiceDescription.

IMPORT_C TPtrC8 CSenXmlServiceDescription::FrameworkVersion ( ) [virtual]

Getter for the framework version.

Returns:: The framework version or KNullDesC8 if not set.

Implements MSenServiceDescription.

virtual IMPORT_C TInt CSenXmlServiceDescription::HasFacetL	(	const TDesC8 &	aURI,
		TBool &	aHasFacet
	)	`[virtual]`

Method for checking if service description has a certain facet.

Parameters:

	aURI	the facet to check, typically some URI.
	aHasFacet	is ETrue if facet is found and EFalse, if not.

Returns:: KErrNone or other system-wide Symbian error codes.

Implements MSenServiceDescription.

virtual IMPORT_C TInt CSenXmlServiceDescription::IapId ( TUint32 & aCurrentIapId ) [virtual]

Getter for IAP ID.

Parameters:

aCurrentIapId

will contain the current Internet Access Point ID

Returns:

KErrNone if <IapId> element is found and has valid content
KErrNotFound if no <IapId> element has been found or it has no content
TLex error codes, if <IapId> element has non-numeric value, which cannot be resolved

Implements MSenProviderPolicy.

virtual IMPORT_C const CSenIdentityProviderIdArray8& CSenXmlServiceDescription::IdentityProviderIds8L ( ) [virtual]

Getter for IdentityProvider IDs.

Returns:: a list of IDP arrays if such value(s) have been set or an empty array if no IDP:s have been specified.

Implements MSenProviderPolicy.

IMPORT_C TBool CSenXmlServiceDescription::Matches ( MSenServiceDescription & aPattern ) [virtual]

Method returns ETrue if this service description matches the given pattern.

The bits of information that are in the pattern are read and compared to corresponding fields in this service description. Note that a pattern may have far fewer fields and that only the non-null and non-zero-length fields are compared. For example, assume that a pattern with only a contract was defined; with the contract set to "urn:example.com:service". Each service description with the same contract will match the pattern, even if such a service description has non-null/non-zero-length fields for other aspects.

Parameters:

aPattern

is a Service Description, typically with partial information.

Returns:: TBool ETrue if match, EFalse otherwise. If the value is not found from current instance, it is not used in comparison (even if offered in the given pattern).

Implements MSenServiceDescription.

Reimplemented in CSenServicePattern.

virtual IMPORT_C const TDesC8& CSenXmlServiceDescription::NewElementName ( ) [virtual]

Method returns the localname for this service description.

This is the localname of the element, when this class is represented as an XML element.

Returns:: descriptor to XML localname of this service description

Reimplemented in CSenIdentityProvider.

static IMPORT_C CSenXmlServiceDescription* CSenXmlServiceDescription::NewL	(	const TDesC8 &	aEndPoint,
		const TDesC8 &	aContract
	)	`[static]`

Standard 2 phase constructors.

Parameters:

	aEndpoint	the service endpoint. Note that endpoint cannot include characters which are illegal in XML. If endpoint is an URL which contains illegal characters (like '&'-char), those need to be encoded into XML entity form (like &). EncodeHttpCharactersLC() method from XmlUtils can be used for encoding of basic XML entities.
	aContract	identifies the service type.

Returns:: a pointer to a new CSenXmlServiceDescription instance

Reimplemented from CSenDomFragment.

Reimplemented in CSenIdentityProvider, and CSenServicePattern.

static IMPORT_C CSenXmlServiceDescription* CSenXmlServiceDescription::NewL ( const TDesC8 & aNamespaceURI ) [static]

Standard 2 phase constructor.

Parameters:

aNamespaceURI

namespace URI for the service description.

Returns:: a pointer to a new CSenXmlServiceDescription instance

Reimplemented from CSenDomFragment.

Reimplemented in CSenIdentityProvider, and CSenServicePattern.

static IMPORT_C CSenXmlServiceDescription* CSenXmlServiceDescription::NewL ( ) [static]

Standard 2 phase constructor.

Returns:: a pointer to a new CSenXmlServiceDescription instance.

Reimplemented from CSenDomFragment.

Reimplemented in CSenServicePattern.

static IMPORT_C CSenXmlServiceDescription* CSenXmlServiceDescription::NewLC	(	const TDesC8 &	aEndPoint,
		const TDesC8 &	aContract
	)	`[static]`

Standard 2 phase constructors.

Parameters:

	aEndpoint	the service endpoint. Note that endpoint cannot include characters which are illegal in XML. If endpoint is an URL which contains illegal characters (like '&'-char), those need to be encoded into XML entity form (like &). EncodeHttpCharactersLC() method from XmlUtils can be used for encoding of basic XML entities.
	aContract	identifies the service type.

Returns:: a pointer to a new CSenXmlServiceDescription instance, which is left on cleanup stack.

Reimplemented in CSenIdentityProvider, and CSenServicePattern.

static IMPORT_C CSenXmlServiceDescription* CSenXmlServiceDescription::NewLC ( const TDesC8 & aNamespaceURI ) [static]

Standard 2 phase constructor.

Parameters:

aNamespaceURI

namespace URI for the service description.

Returns:: a pointer to a new CSenXmlServiceDescription instance, which is left on cleanup stack.

Reimplemented in CSenIdentityProvider, and CSenServicePattern.

static IMPORT_C CSenXmlServiceDescription* CSenXmlServiceDescription::NewLC ( ) [static]

Standard 2 phase constructor.

Returns:: a pointer to a new CSenXmlServiceDescription instance, which is left on cleanup stack.

Reimplemented in CSenServicePattern.

virtual IMPORT_C TInt CSenXmlServiceDescription::RebuildFrom ( MSenProviderPolicy & aTemplate ) [virtual]

Method reads provider policy class instance values from given template.

Values may include an IAP ID, preferred IdentityProvider IDs etc.

Parameters:

aTemplate

from which the values are read.

Returns:: KErrNone Everything went ok. KErrAlreadyExists Duplicates were found KErrArgument Invalid providerIds were found Other error codes are system-wide Symbian error codes.

Implements MSenProviderPolicy.

virtual IMPORT_C TInt CSenXmlServiceDescription::RemoveFacet ( const TDesC8 & aURI ) [virtual]

Removes a characteristic (Facet) from the description.

Parameters:

aURI

of the facet to be removed.

Returns:: KErrNone if a Facet was successfully removed KErrNotFound if a Facet could not be found Other system-wide Symbian error codes.

Implements MSenServiceDescription.

IMPORT_C void CSenXmlServiceDescription::ResumeParsingFromL	(	const TDesC8 &	aNsUri,
		const TDesC8 &	aLocalName,
		const TDesC8 &	aQName
	)	`[virtual]`

Resumes the parsing.

Called by the delegate fragment in order to notify owner, which needs to regain (take over) parsing. For example, when a policy fragment is parsed, the service description fragment should resume parsing the rest of its own XML document representation.

Parameters:

	aNsUri	The namespace URI of the current element
	aLocalName	The local name of the current element
	aQName	The qualified name of the current element

Reimplemented from CSenDomFragment.

virtual IMPORT_C TInt CSenXmlServiceDescription::ScoreMatchL ( MSenServiceDescription & aPattern ) [virtual]

Method returns a positive integer if this ServiceDescription matches the given pattern in at least one aspect.

Higher numbers mean a closer match. The bits of information that are in the pattern are read and compared to corresponding fields in this ServiceDescription. Note that a pattern may have far fewer fields and that only the non-null fields are compared. For example, assume that a pattern with only a contract was defined; with the contract set to "urn:example.com:service". Each ServiceDescription with the same contract will match the pattern, even if such a ServiceDescription has non-null fields for other aspects.

Parameters:

aPattern

a ServiceDescription, typically with partial information.

Returns:: the score. If nothing matches, returns 0

Implements MSenServiceDescription.

IMPORT_C void CSenXmlServiceDescription::SetAttributesL ( const RAttributeArray & aAttributes ) [virtual]

Method looks for FrameworkID attribute from the given XML attribute array and if one is found, sets its value for this instance.

In addition, all the namespace attributes are copied. All other attributes are discarded.

Parameters:

aAttributes

the attribute list.

Reimplemented from CSenDomFragment.

IMPORT_C void CSenXmlServiceDescription::SetContractL ( const TDesC8 & aContract ) [virtual]

Setter for contract.

Parameters:

aContract

the contract to be set.

Implements MSenServiceDescription.

IMPORT_C void CSenXmlServiceDescription::SetEndPointL ( const TDesC8 & aEndPoint ) [virtual]

Setter for endpoint.

Parameters:

aEndpoint

to the service. Note that endpoint cannot include characters which are illegal in XML. If endpoint is an URL which contains illegal characters (like '&'-char), those need to be encoded into XML entity form (like &). EncodeHttpCharactersLC() method from XmlUtils can be used for encoding of basic XML entities.

Implements MSenServiceDescription.

virtual IMPORT_C TInt CSenXmlServiceDescription::SetFacetL ( const CSenFacet & aFacet ) [virtual]

Method for setting a facet.Adds a new facet, if non-existent.

But, if a facet with same name exists, it will be overridden.

Parameters:

aFacet

to be set. A copy of the original will be created.

Returns:: KErrNotFound if facet can not be found KErrNone if facet was found KErrNoMemory if no memory could be allocated for the value Other system-wide Symbian error codes.

Implements MSenServiceDescription.

IMPORT_C void CSenXmlServiceDescription::SetFrameworkIdL

(

const TDesC8 &

aFrameworkID

)

Setter for the framework ID.

The developer may use a FrameworkID to search for a session of (i.e. connection to) a certain service invocation framework.

Parameters:

aFrameworkId

If set to KNullDesC8, then any matching framework may be used. The default frameworkID in WSF is "ID-WSF" (KDefaultIdWsfFrameworkID). Note that Basic Web Services MUST use "WS-I" (KDefaultBasicWebServicesFrameworkID).

virtual IMPORT_C void CSenXmlServiceDescription::SetIapIdL ( TUint32 aIapId ) [virtual]

Setter for Internet Access Point (IAP) ID.

Method is used to define default access point to avoid IAP selection dialog prompt.

Parameters:

aIapId

is the ID found from CommDB.

Implements MSenProviderPolicy.

virtual IMPORT_C void CSenXmlServiceDescription::SetIdentityProviderIdsL ( CSenIdentityProviderIdArray8 & aList ) [virtual]

Setter for IdentityProvider IDs.

Overrides current values with the given values from the array. When initiating a new service connection, this list of ProviderIDs define, which IdentityProviders are preferred OR which are strictly acceptable ones.

Parameters:

aList

list of IdentityProvider IDs.

Implements MSenProviderPolicy.

virtual IMPORT_C void CSenXmlServiceDescription::StartElementL	(	const TDesC8 &	aNsUri,
		const TDesC8 &	aLocalName,
		const TDesC8 &	aQName,
		const RAttributeArray &	aAttributes
	)	`[protected, virtual]`

Callback function which implements the XML content handler interface.

Parameters:

	aNsURI	The namespace URI of the new element
	aLocalName	The local name of the new element
	aQName	The qualified name of the new element
	aAttributes	The attributes of the new element