1 /*

     2 * Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  AT extension client API

    15 *

    16 */

    17 

    18 

    19 #ifndef R_ATEXTCLIENT_H

    20 #define R_ATEXTCLIENT_H

    21 

    22 #include <e32base.h>

    23 #include <atextpluginbase.h>

    24 

    25 /**  Interface definitions; either DUN or HFP */

    26 enum TATExtensionInterface

    27     {

    28     EDunATExtension,

    29     EHfpATExtension

    30     };

    31 

    32 /**  ECOM notification type for plugins */

    33 enum TATExtensionEcomType

    34     {

    35     EEcomTypeUninstall,

    36     EEcomTypeInstall

    37     };

    38 

    39 /**

    40  *  Client of AT Extension.

    41  *

    42  *  @lib atextclient.lib

    43  *  @since S60 v5.0

    44  */

    45 NONSHARABLE_CLASS( RATExt ) : public RSessionBase

    46     {

    47 

    48 public:

    49 

    50     /**

    51      * Establishes a session with server and connect to corresponding extension

    52      * plugins specified by parameter TATExtensionInterface.

    53      *

    54      * @since S60 v5.0

    55      * @param aIf The AT extension interface

    56      * @param aName Connection identifier name

    57      * @return Symbian error code on error, KErrNone otherwise

    58      */

    59     IMPORT_C TInt Connect( TATExtensionInterface aIf,

    60                            const TDesC8& aName );

    61 

    62     /**

    63      * Synchronously closes the session

    64      * Optional: client can do either Close() or SynchronousClose()+Close()

    65      *

    66      * @since S60 v5.0

    67      * @return Symbian error code on error, KErrNone otherwise

    68      */

    69     IMPORT_C TInt SynchronousClose();

    70 

    71     /**

    72      * Handles a command.

    73      *

    74      * @since S60 v5.0

    75      * @param aStatus The request status

    76      * @param aCmd The command to be handled.

    77      * @param aReply The descriptor to hold reply to this command;

    78      * @param aRemainingReplyLength Tells the length of remaining reply if it is not 0;

    79      *                              the remainings can be fetched by GetNextPartOfReply().

    80      * @param aReplyType Reply type for the handled AT command

    81      * @return Symbian error code on error, KErrNone otherwise

    82      */

    83     IMPORT_C TInt HandleCommand( TRequestStatus& aStatus,

    84                                  const TDesC8& aCmd,

    85                                  TBuf8<KDefaultCmdBufLength>& aReply,

    86                                  TPckg<TInt>& aRemainingReplyLength,

    87                                  TPckg<TATExtensionReplyType>& aReplyType );

    88 

    89     /**

    90      * Cancels a command handling request.

    91      *

    92      * @since S60 v5.0

    93      * @return Symbian error code on error, KErrNone otherwise

    94      */

    95     IMPORT_C TInt CancelHandleCommand();

    96 

    97     /**

    98      * Gets the remaining reply of a previous handled command.

    99      *

   100      * @since S60 v5.0

   101      * @param aReply The descriptor to hold the reply;

   102      * @param aRemainingReplyLength tells the length of remaining reply if it is not 0;

   103      *                              the remainings can be fetched by GetNextPartOfReply().

   104      * @return Symbian error code on error, KErrNone otherwise

   105      */

   106     IMPORT_C TInt GetNextPartOfReply( TBuf8<KDefaultCmdBufLength>& aReply,

   107                                       TInt& aRemainingReplyLength );

   108 

   109     /**

   110      * Number of plugins

   111      *

   112      * @since S60 v5.0

   113      * @return The number of plugins

   114      */

   115     IMPORT_C TInt NumberOfPlugins();

   116 

   117     /**

   118      * Receives unsolicited result code from extension plugins.

   119      *

   120      * @since S60 v5.0

   121      * @param aStatus The request status

   122      * @param aRecvBuffer The receiving buffer

   123      * @param aUrcPluginUid UID of the plugin

   124      * @return Symbian error code on error, KErrNone otherwise

   125      */

   126     IMPORT_C TInt ReceiveUnsolicitedResult( TRequestStatus& aStatus,

   127                                             TBuf8<KDefaultUrcBufLength>& aRecvBuffer,

   128                                             TPckg<TUid>& aUrcPluginUid );

   129 

   130     /**

   131      * Cancels a pending receiving request.

   132      *

   133      * @since S60 v5.0

   134      * @param aUrcPluginUid UID of the plugin

   135      * @return Symbian error code on error, KErrNone otherwise

   136      */

   137     IMPORT_C TInt CancelReceiveUnsolicitedResult( TUid& aUrcPluginUid );

   138 

   139     /**

   140      * Marks URC handling ownership.

   141      *

   142      * @since S60 v5.0

   143      * @param aUrcPluginUid UID of the plugin

   144      * @return Symbian error code on error, KErrNone otherwise

   145      */

   146     IMPORT_C TInt MarkUrcHandlingOwnership( TUid& aUrcPluginUid );

   147 

   148     /**

   149      * Receives ECOM plugin uninstall/install/version reports

   150      *

   151      * @since S60 5.0

   152      * @param aStatus The request status

   153      * @param aPluginUid UID of the plugin

   154      * @param aEcomType Ecom type for the update

   155      * @return Symbian error code on error, KErrNone otherwise

   156      */

   157     IMPORT_C TInt ReceiveEcomPluginChange(

   158         TRequestStatus& aStatus,

   159         TPckg<TUid>& aPluginUid,

   160         TPckg<TATExtensionEcomType>& aEcomType );

   161 

   162     /**

   163      * Cancels ECOM plugin uninstall/install/version report receiving

   164      *

   165      * @since S60 5.0

   166      * @return Symbian error code on error, KErrNone otherwise

   167      */

   168     IMPORT_C TInt CancelReceiveEcomPluginChange();

   169 

   170     /**

   171      * Reports change to quiet mode.

   172      * The quiet mode is off by default.

   173      *

   174      * @since S60 5.0

   175      * @param aMode ETrue if quiet mode changed on, EFalse if off

   176      * @return Symbian error code on error, KErrNone otherwise

   177      */

   178     IMPORT_C TInt ReportQuietModeChange( TBool aMode );

   179 

   180     /**

   181      * Reports change to verbose mode.

   182      * The verbose mode is on by default.

   183      *

   184      * @since S60 5.0

   185      * @param aMode ETrue if verbose mode changed on, EFalse if off

   186      * @return Symbian error code on error, KErrNone otherwise

   187      */

   188     IMPORT_C TInt ReportVerboseModeChange( TBool aMode );

   189 

   190     /**

   191      * Reports change to a value of a character

   192      *

   193      * @since S60 5.0

   194      * @param aCharType New character's type

   195      * @param aNewChar New character value

   196      * @return Symbian error code on error, KErrNone otherwise

   197      */

   198     IMPORT_C TInt ReportCharacterChange( TATExtensionCharType aCharType,

   199                                          TInt8 aNewChar );

   200 

   201     /**

   202      * Reporter for reporting when client side has updated its internal

   203      * information after ReceiveEcomPluginChange()

   204      *

   205      * @since S60 5.0

   206      * @param aPluginUid UID of the plugin

   207      * @param aUpdateType Type of update

   208      * @return Symbian error code on error, KErrNone otherwise

   209      */

   210     IMPORT_C TInt ReportListenerUpdateReady( TUid& aPluginUid,

   211                                              TATExtensionEcomType aUpdateType );

   212 

   213     /**

   214      * Broadcasts NVRAM status change to the plugins.

   215      *

   216      * @since S60 5.0

   217      * @param aNvram New NVRAM status. The new settings (delimited by "|")

   218      *               must differ from the Hayes defaults.

   219      * @return Symbian error code on error, KErrNone otherwise

   220      */

   221     IMPORT_C TInt BroadcastNvramStatusChange( const TDesC8& aNvram );

   222 

   223     /**

   224      * Reports about external handle command error condition.

   225      * This is for cases when for example DUN decided the reply contained an

   226      * error condition but the plugin is still handling the command internally.

   227      * Example: "AT+TEST;+TEST2" was given in command line; "AT+TEST" returns

   228      * non-EReplyTypeError condition and "AT+TEST2" returns EReplyTypeError.

   229      * As the plugin(s) returning the non-EReplyTypeError may still have some

   230      * ongoing operation then these plugins are notified about the external

   231      * EReplyTypeError in command line processing. It is to be noted that

   232      * HandleCommandCancel() is not sufficient to stop the processing as the

   233      * command handling has already finished.

   234      *

   235      * @since S60 5.0

   236      * @return Symbian error code on error, KErrNone otherwise

   237      */

   238     IMPORT_C TInt ReportExternalHandleCommandError();

   239 

   240     /**

   241      * Reports about abort condition in command handling.

   242      * This is for cases when for example DUN decided an abort condition was

   243      * received from DTE (ITU-T V.250 5.6.1). This API is for notifying the

   244      * plugin that abort was requested. However the plugin currently handling

   245      * the command may ignore the request if it doesn't support abort for the

   246      * command or it may return the changed condition with

   247      * HandleCommandCompleted()

   248      *

   249      * @since S60 5.0

   250      * @param aStop If ETrue stop command line processing

   251      *              If EFalse continue command line processing

   252      * @return Symbian error code on error, KErrNone otherwise

   253      */

   254     IMPORT_C TInt ReportHandleCommandAbort( TBool& aStop );

   255 

   256     /**

   257      * Gets the next special command RSS file entry. These commands are commands

   258      * with a matching start but with any ending sequence. Command "ATD*99***1#"

   259      * is one of these and the number of these commands should be kept minimal.

   260      *

   261      * @since S60 5.0

   262      * @param aCmd The next found special command

   263      * @param aFirstSearch If ETrue the search is done from the start,

   264      *                     If EFalse the search continues from the old position.

   265      *                     ATEXT sets this to EFalse after each successfull call.

   266      * @return Symbian error code on error, KErrNone otherwise

   267      */

   268     IMPORT_C TInt GetNextSpecialCommand( TDes8& aCmd,

   269                                          TBool& aFirstSearch );

   270 

   271 private:  // data

   272 

   273     /**

   274      * Connected interface

   275      */

   276     TATExtensionInterface iConnectedIf;

   277 

   278     };

   279 

   280 #endif  // R_ATEXTCLIENT_H