/*
* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
* Name : SdpMediaField.h
* Part of : SDP Codec
* Interface : SDK API, SDP Codec API
* Version : 1.0
*
*/
#ifndef CSDPMEDIAFIELD_H
#define CSDPMEDIAFIELD_H
// INCLUDES
#include <e32base.h>
#include "_sdpdefs.h"
#include <stringpool.h>
// FORWARD DECLARATIONS
class RReadStream;
class RWriteStream;
class CSdpConnectionField;
class CSdpBandwidthField;
class CSdpAttributeField;
class CSdpKeyField;
class CSdpFmtAttributeField;
class CSdpCodecParseUtil;
// CLASS DECLARATION
/**
* @publishedAll
* @released
*
* This class encapsulates the media description field and related media
* specific subfields of the Session Description Protocol.
*
* The normative reference for correct formatting and values is
* draft-ietf-mmusic-sdp-new-14 unless specified otherwise in
* member documentation. The implementation supports this normative
* reference, but does not enforce it fully.
*
* @lib sdpcodec.lib
*/
class CSdpMediaField : public CBase
{
public:
public: // Constructors and destructor
/**
* Constructs a new media description field.
*
* @param aText A correctly formatted media field
* terminated by a CRLF followed by zero or more media
* attribute fields separated by a CRLF.
* @param aRecurse If ETrue, attempts to construct also media
* attributes following the CRLF terminating the media field.
* @return a new instance.
*/
IMPORT_C static CSdpMediaField* DecodeL(const TDesC8& aText,
TBool aRecurse = ETrue);
/**
* Constructs a new media description field and adds the pointer to
* the cleanup stack.
*
* @param aText A correctly formatted media field
* terminated by a CRLF followed by zero or more media
* attribute fields separated by a CRLF.
* @param aRecurse If ETrue, attempts to construct also media
* attributes following the CRLF terminating the media field.
* @return a new instance.
*/
IMPORT_C static CSdpMediaField* DecodeLC(const TDesC8& aText,
TBool aRecurse = ETrue);
/**
* Constructs a new media description field.
* The optional portcount component of the field is initialized to 1.
*
* @param aMedia A valid media type name.
* @param aPort Port number.
* @param aProtocol A valid media protocol name.
* @param aFormatList A valid format list.
* @return a new instance.
*/
IMPORT_C static CSdpMediaField* NewL(RStringF aMedia,
TUint aPort,
RStringF aProtocol,
const TDesC8& aFormatList);
/**
* Constructs a new media description field and adds the pointer to
* the cleanup stack.
* The optional portcount component of the field is initialized to 1.
*
* @param aMedia A valid media type name.
* @param aPort Port number.
* @param aProtocol A valid media protocol name.
* @param aFormatList A valid format list.
* @return a new instance.
*/
IMPORT_C static CSdpMediaField* NewLC(RStringF aMedia,
TUint aPort,
RStringF aProtocol,
const TDesC8& aFormatList);
/**
* Deletes the resources held by the instance.
*/
IMPORT_C ~CSdpMediaField();
public: // New functions
/**
* Outputs the field formatted according to SDP syntax and including
* the terminating CRLF. Optionally output also the related media
* level fields.
*
* @param aStream Stream used for output. On return the
* stream includes correctly formatted media field with
* media part fields if aRecurse is defined to ETrue.
* @param aRecurse Flag to specify whether to output media
* attributes also (ETrue) or only the media field (EFalse).
*/
IMPORT_C void
EncodeL(RWriteStream& aStream, TBool aRecurse = ETrue) const;
/**
* Creates a new instance that is equal to the target.
* Optionally also related subfields are cloned.
*
* @param aRecurse Flag to specify whether to clone subfields
* also (ETrue) or only the media field (EFalse).
* @return a new instance.
*/
IMPORT_C CSdpMediaField * CloneL(TBool aRecurse = ETrue) const;
/**
* Compares this instance to another for equality. Subfields are
* included in the comparison if present.
*
* @param aObj The instance to compare to.
* @return ETrue if equal, EFalse if not.
*/
IMPORT_C TBool operator == (const CSdpMediaField& aObj) const;
/**
* Checks the consistency between the media field and it's subfields.
* In particular, this function checks that each format specific
* attribute is related to a format in the format list of the
* media field.
*
* @return ETrue if media description is consistent and EFalse if not.
*/
IMPORT_C TBool IsValid() const;
/**
* Gets the media type.
*
* @return The media type.
*/
IMPORT_C RStringF Media() const;
/**
* Sets the media type.
*
* @param aMedia The media type.
* @leave KErrSdpCodecMediaField if aMedia is not valid character
*/
IMPORT_C void SetMediaL(RStringF aMedia);
/**
* Gets the media protocol.
*
* @return The media protocol.
*/
IMPORT_C RStringF Protocol() const;
/**
* Sets the media protocol.
*
* @param aProtocol The media protocol.
* @leave KErrSdpCodecMediaField if
* aProtocol containing two elements divided by slash are not
* valid tokens.
*/
IMPORT_C void SetProtocolL(RStringF aProtocol);
/**
* Gets the port number.
*
* @return The port number.
*/
IMPORT_C TUint Port() const;
/**
* Sets the port number.
*
* @param aPort The port number.
* @leave KErrSdpCodecMediaField if port is not valid number as
* defined in draft-ietf-mmusic-sdp-new-14
*/
IMPORT_C void SetPortL(TUint aPort);
/**
* Gets the port count.
*
* @return The port count.
*/
IMPORT_C TUint PortCount() const;
/**
* Sets the port count.
*
* @param aCount The port count that must be greater than zero.
* @leave KErrSdpCodecMediaField if aCount equals to zero.
*/
IMPORT_C void SetPortCountL(TUint aCount);
/**
* Gets the format list.
*
* @return The format list.
*/
IMPORT_C const TDesC8& FormatList() const;
/**
* Sets the format list.
* The format list should contain one or more format tokens separated
* by a single whitespace character.
*
* @param aValue A valid format list.
* @leave KErrSdpCodecMediaField if aValue contains invalid tokens
*/
IMPORT_C void SetFormatListL(const TDesC8& aValue);
/**
* Return the media level info field value.
*
* @return The value or an empty descriptor if not present.
*/
IMPORT_C const TDesC8& Info() const;
/**
* Sets the media level info field value.
*
* @param aValue A valid info field value.
* @leave KErrSdpCodecMediaInfoField if aValue is not KNullDesC8 or
* aValue includes invalid byte strings (´\0´, ´\n´, ´\r´).
*/
IMPORT_C void SetInfoL(const TDesC8& aValue);
/**
* Gets the media level encryption key field.
* Note, that the ownership is not transferred and
* the instance must not be deleted by the caller.
*
* @return Encryption key field or null if not present.
*/
IMPORT_C CSdpKeyField* Key();
/**
* Gets the media level encryption key field.
*
* @return Encryption key field or null if not present.
*/
IMPORT_C const CSdpKeyField* Key() const;
/**
* Sets or removes the media level encryption key field.
*
* @param aObj The new key field or null if field is
* to be removed. Ownership of the referenced object
* is transferred to the media field instance.
*/
IMPORT_C void SetKey(CSdpKeyField* aObj);
/**
* Gets the set of media format level attributes.
* This array is used directly for element insertion and removal.
*
* The objects referenced from the array are owned by the media
* field instance and must not be deleted. An object can be
* removed from the media description by setting the corresponding
* element to zero. By doing so, the calling party receives ownership
* of the removed object.
*
* @return The set of media format level attributes.
*/
IMPORT_C RPointerArray<CSdpFmtAttributeField>& FormatAttributeFields();
/**
* Gets the set of media level, format independent attributes.
* This array is used directly for element insertion and removal.
*
* The objects referenced from the array are owned by the media
* field instance and must not be deleted. An object can be
* removed from the media description by setting the corresponding
* element to zero. By doing so, the calling party receives ownership
* of the removed object.
*
* @return The set of media level attributes.
*/
IMPORT_C RPointerArray<CSdpAttributeField>& AttributeFields();
/**
* Gets the set of media level bandwidth fields.
* This array is used directly for element insertion and removal.
*
* The objects referenced from the array are owned by the media
* field instance and must not be deleted. An object can be
* removed from the media description by setting the corresponding
* element to zero. By doing so, the calling party receives ownership
* of the removed object.
*
* @return The set of media level bandwidth fields.
*/
IMPORT_C RPointerArray<CSdpBandwidthField>& BandwidthFields();
/**
* Gets the set of media level connection fields.
* This array is used directly for element insertion and removal.
*
* The objects referenced from the array are owned by the media
* field instance and must not be deleted. An object can be
* removed from the media description by setting the corresponding
* element to zero. By doing so, the calling party receives ownership
* of the removed object.
*
* @return The set of media level connection fields.
*/
IMPORT_C RPointerArray<CSdpConnectionField>& ConnectionFields();
/**
* Removes a specific format from the media description.
* The function will remove the named format from the format list if
* found and then delete all format level attributes of type
* CSdpFmtAttributeField related to the removed format.
*
* @param aFormat The name of the format to remove.
*/
IMPORT_C void RemoveFormatL(const TDesC8& aFormat);
/**
* Removes all formats except one from the media description.
* The function will set the format list to only contain the one
* format to keep and then delete all format level attributes that
* are related to the removed formats. If the format is not found
* from the format list, it is added there. If there are no format
* level attributes for the specified format, the format level
* attribute set will be empty.
*
* @param aFormat The name of the format to keep after
* removing all others.
*/
IMPORT_C void KeepFormatL(const TDesC8& aFormat);
/**
* Sets this media description into rejected state.
* The rejected state is defined by the offer/answer model in
* RFC3264. The function sets the port number to 0 and removes
* all formats except one. The remaining format is determined
* by the implementation.
*/
IMPORT_C void RejectMedia();
public:
/**
* Shows if contact is present
*
* @return ETrue if contact present, otherwise EFalse
*/
TBool IsContactPresent() const;
/**
* Externalizes the object to stream
*
* @param aStream Stream where the object's state will be stored
*/
void ExternalizeL(RWriteStream& aStream) const;
/**
* Creates object from the stream data
*
* @param aStream Stream where the object's state will be read
* @return Initialized object
*/
static CSdpMediaField* InternalizeL(RReadStream& aStream);
private:
CSdpMediaField();
void ConstructL();
void ConstructL(TBool aRecurse);
void ConstructL(RStringF aMedia, TUint aPort, RStringF aProtocol,
const TDesC8& aFormatList);
void ConstructL(const CSdpMediaField& aSdpMediaField);
void DoInternalizeL(RReadStream& aStream);
void ParseL (const TDesC8& aText);
void ParseMediaL();
void ParseInformationL();
void ParseConnectionL();
void ParseBandwithL();
void ParseEncryptionKeyL();
void ParseAttributeFieldsL();
TDesC8& GetTokenFromStreamL(RReadStream& aStream);
CSdpMediaField(const CSdpMediaField&); // Hidden.
CSdpMediaField& operator = (const CSdpMediaField&); // Hidden
private: // Data
HBufC8* iInfo;
CSdpKeyField* iSdpKeyField;
RArray<TPtrC8> iElementArray;
RStringPool iPool;
TBool iRecurse;
RStringF iMedia;
RStringF iProtocol;
TUint iPort;
TUint iPortCount;
HBufC8* iFormatList;
RPointerArray<CSdpBandwidthField>* iBandwidthFields;
RPointerArray<CSdpAttributeField>* iAttributeFields;
RPointerArray<CSdpConnectionField>* iConnectionFields;
RPointerArray<CSdpFmtAttributeField>* iFmtAttrFields;
HBufC8* iToken;
CSdpCodecParseUtil* iSdpCodecParseUtil;
};
#endif // CSDPMEDIAFIELD_H