--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/phonesrv_plat/voice_mailbox_number_api/inc/cvoicemailbox.h Tue Aug 31 15:45:17 2010 +0300
@@ -0,0 +1,360 @@
+/*
+* Copyright (c) 2009-2010 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Interface for fetching/saving the vmbx entries.
+* Also notify on a number change is supported.
+* Interface : External, CVoiceMailbox
+*
+*/
+
+#ifndef C_VOICEMAILBOX_H
+#define C_VOICEMAILBOX_H
+
+// INCLUDES
+#include <voicemailboxdefs.h>
+
+// FORWARD DECLARATIONS
+class MVoiceMailboxObserver;
+class CVoiceMailboxImpl;
+class CVoiceMailboxEntry;
+
+/**
+ * Parameter package for Voice Mailbox API operations.
+ *
+ * @lib vmbxengine.lib
+ */
+class TVoiceMailboxParams
+ {
+public:
+ /**
+ * Version of parameter package.
+ */
+ IMPORT_C TInt Version();
+
+ /**
+ * Default constructor.
+ */
+ IMPORT_C TVoiceMailboxParams();
+
+ /**
+ * Constructor for CVoiceMailboxEntry
+ */
+ IMPORT_C TVoiceMailboxParams( const CVoiceMailboxEntry& aEntry );
+
+public:
+
+ /**
+ * Mailbox type.
+ */
+ TVmbxType iType;
+
+ /**
+ * Mailbox service id.
+ */
+ TServiceId iServiceId;
+
+ /**
+ * Mailbox line type.
+ * Initialized to EVmbxAlsLineDefault.
+ */
+ TVmbxAlsLineType iLineType;
+
+protected:
+
+ /**
+ * TVoiceMailboxParams package version.
+ */
+ TInt iVersion;
+
+};
+
+/**
+ * CVoiceMailbox offers an interface for fetching and saving
+ * voice mailbox entries.
+ * The API offers also services for querying a new number or to
+ * change an existing one.
+ *
+ * @code
+ *
+ * In this example user selects type of a mailbox to use. Then number
+ * of selected mailbox is fetched. If number wasn't set, then user
+ * is queried to enter a number for the selected mailbox.
+ *
+ * // Creates instance of CVoiceMailbox
+ * CVoiceMailbox* voicemailbox = CVoiceMailbox::NewLC();
+ *
+ * // Selected mailbox type
+ * TVoiceMailboxParams vmbxParams;
+ *
+ * //Launch type selection query
+ * TInt error = voicemailbox->QueryVmbxType( vmbxParams );
+ *
+ * CVoiceMailboxEntry* vmbxEntry = NULL;
+ *
+ * if ( KErrNone == error )
+ * {
+ * if ( KErrNone ==
+ * voicemailbox->GetStoredEntry( vmbxParams, vmbxEntry ) )
+ * {
+ * // Number retrieved succesfully, do appropriate tasks, e.g.:
+ * TPtrC ptrNumber( KNullDesC );
+ * TInt numError = vmbxEntry->GetVmbxNumber( ptrNumber );
+ * if ( KErrNone == numError && ptrNumber.Length() )
+ * {
+ * // Do appropriate tasks, e.g dial a call.
+ * }
+ * }
+ * }
+ * else if ( KErrNotFound == error )
+ * {
+ * // No number defined, query new entry from user
+ * error = voicemailbox->QueryNewEntry( vmbxParams, vmbxEntry );
+ * if ( KErrNone == error )
+ * {
+ * // Do appropriate tasks, e.g. save and dial a call.
+ * error = voicemailbox->SaveEntry( *vmbxEntry );
+ * // For example get the number/address using
+ * // vmbxEntry->GetVmbxNumber() and then dial a call
+ * }
+ * // else: problem getting the new number/address, e.g. skip
+ * }
+ *
+ * else
+ * {
+ * // User cancelled or no supported mailboxes configured
+ * }
+ *
+ * delete vmbxEntry; // Entry ownership was transferred
+ * vmbxEntry = NULL;
+ * CleanupStack::PopAndDestroy( voicemailbox );
+ * voicemailbox = NULL;
+ * @endcode
+ *
+ * @lib vmbxengine.lib
+ * @since S60 v5.2
+ */
+
+class CVoiceMailbox : public CBase
+ {
+public:
+
+ /**
+ * Static constructor.
+ * @return New instance of the object. Ownership transferred.
+ */
+ IMPORT_C static CVoiceMailbox* NewL();
+
+ /**
+ * Static constructor.
+ * @return New instance of the object. Ownership transferred.
+ */
+ IMPORT_C static CVoiceMailbox* NewLC();
+
+ /**
+ * Destructor.
+ */
+ virtual ~CVoiceMailbox();
+
+public:
+
+ /**
+ * Retrieves voice mailbox entry for the specified service.
+ *
+ * @param in Params Service id and type of the mailbox for which
+ * a number/address should be defined.
+ * @param out aEntry If successful, a new result container is
+ * created and ownership passed to the caller.
+ * @return - KErrNone if an entry is found.
+ * - KErrNotFound if no entry available
+ * - KErrArgument when illegal argument
+ * - Other system wide errors.
+ */
+ IMPORT_C virtual TInt GetStoredEntry(
+ const TVoiceMailboxParams& aParams,
+ CVoiceMailboxEntry*& aEntry ) const;
+
+ /**
+ * Saves the vmbx entry to its storage.
+ *
+ * Some mailbox types may not support saving all arguments.
+ * In that case unsupported arguments are ignored.
+ * This method may display related UI notes or queries.
+ *
+ * @param in aEntry The vmbx entry to save.
+ * @return - KErrNone if the entry was saved
+ * - KErrNotSupported if not capable or allowed to execute this
+ * for the specified mailbox service.
+ * - KErrArgument When illegal argument was passed.
+ * - Other system wide errors.
+ */
+ IMPORT_C virtual TInt SaveEntry( const CVoiceMailboxEntry& aEntry );
+
+ /**
+ * Displays a query asking the user to define a mailbox number/address.
+ * Returns the input which the user entered, but does not save it.
+ * For that caller has to use SaveEntry().
+ * This method may display related UI notes or queries.
+ *
+ * If editing for the specified mailbox service is not allowed,
+ * this method displays an error note and returns an error.
+ * If client is interested, CheckConfiguration()
+ * can be used to check permissions.
+ *
+ *
+ * @param in aParams Service id and type of the mailbox for which
+ * a number/address should be defined.
+ * @param out aEntry If successful, a new result container is
+ * created and ownership passed to the caller.
+ * @return - KErrNone if the number was entered.
+ * - KErrNotFound if the number is not defined
+ * (user entered no number or selected Cancel)
+ * - KErrArgument When illegal argument.
+ * - KErrNotSupported if not capable or allowed to execute this
+ * for the specified mailbox.
+ * - Other system wide errors.
+ */
+ IMPORT_C virtual TInt QueryNewEntry(
+ const TVoiceMailboxParams& aParams,
+ CVoiceMailboxEntry*& aEntry );
+
+ /**
+ * Displays a query asking the user to change a mailbox number/address.
+ * Returns the input from user, but does not save it.
+ * For that caller has to use SaveEntry().
+ *
+ * If editing for the specified mailbox service is not allowed,
+ * this method displays an error note and returns an error.
+ * If client is interested, CheckConfiguration()
+ * can be used to check permissions.
+ *
+ * @param in aParams Service id and type of the mailbox.
+ * @param out aEntry If successful, a new result container is
+ * created and ownership passed to the caller.
+ * @return - KErrNone if the number was entered.
+ * aNumber will contain the vmbx number.
+ * - KErrCancel If the user selected Cancel.
+ * - KErrArgument When illegal argument.
+ * - KErrNotSupported if not capable or allowed to execute this
+ * for the specified mailbox.
+ * - Other system wide errors.
+ */
+ IMPORT_C virtual TInt QueryChangeEntry(
+ const TVoiceMailboxParams& aParams, CVoiceMailboxEntry*& aEntry );
+
+ /**
+ * Displays a query on the screen asking the user to select a
+ * Voice Mailbox service.
+ *
+ * @param out aParams If successful,
+ * contains selected mailbox info.
+ * @return - KErrNone if successful.
+ * - KErrCancel if user selected Cancel
+ * - KErrNotFound if there is no defined voice number and
+ * user have selected the type to define or the default
+ * type given.
+ * - Other system wide errors.
+ */
+ IMPORT_C virtual TInt QueryVmbxType(
+ TVoiceMailboxParams& aParams );
+
+ /**
+ * Issues a notify request on a vmbx number/address change.
+ *
+ * The observer callback will be called whenever any vmbx number/address
+ * has changed on those mailboxes which support observing.
+ *
+ * Only one notify request can be pending. Method will leave with KErrInUse
+ * if a second request is issued while one is active already.
+ * Leaves if the notify request could not be served.
+ *
+ * @param in aObserver The observer for the notification.
+ * @param in aNotifyOnActiveLineOnly if this is ETrue, notify events will
+ * be generated only if the vmbx number of the active ALS line is
+ * changed, not if the number of the other line is changed. When
+ * there is no ALS support, this has no effect ie. notification
+ * will be generated always.
+ */
+ IMPORT_C virtual void NotifyVmbxNumberChangeL(
+ MVoiceMailboxObserver& aObserver,
+ const TBool aNotifyOnActiveLineOnly );
+
+ /**
+ * Cancels a notify request on a vmbx number change.
+ *
+ */
+ IMPORT_C virtual void NotifyVmbxNumberChangeCancel();
+
+ /**
+ * Checks the Voice Mailbox configuration to find out if a features
+ * are disabled or enabled.
+ *
+ * @param in aParams Specifies which mailbox capabilities,
+ * the caller wants to check.
+ * @param in aFlags Use TVmbxFeatureCapabilityFlag values
+ * for this parameter.
+ * Specifies what features client wants to check.
+
+ * @return True if feature(s) enabled.
+ */
+ IMPORT_C virtual TBool CheckConfiguration(
+ const TVoiceMailboxParams& aParams,
+ const TInt aFlags );
+
+
+ /**
+ * Checks the Voice Mailbox how many VoIP service Ids
+ *
+ * @param out aProfileIds
+ * @return KErrNone if get service Ids successfully.
+ */
+ IMPORT_C virtual TInt GetServiceIds( RIdArray& aProfileIds ) const;
+
+ /**
+ * Saves provisioned entry to corresponding storage.
+ *
+ * Some mailbox types may not support saving all arguments.
+ * In that case unsupported arguments are ignored.
+ *
+ * @param in aEntry The provisioned vmbx entry to save.
+ * @return - KErrNone if the entry was saved
+ * - KErrNotSupported if not capable or allowed to execute this
+ * for the specified mailbox service.
+ * - KErrArgument When illegal argument was passed.
+ * - Other system wide errors.
+ */
+ IMPORT_C TInt SaveProvisionedEntry( const CVoiceMailboxEntry& aEntry );
+
+protected:
+
+ /**
+ * Second phase constructor.
+ *
+ */
+ void ConstructL();
+
+ /**
+ * Default constructor.
+ *
+ */
+ CVoiceMailbox();
+
+private: // data
+
+ /**
+ * Implementation of the client API.
+ * Own.
+ **/
+ CVoiceMailboxImpl* iBody;
+ };
+
+#endif // C_VOICEMAILBOX_H