1 /*

     2 * Copyright (c) 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:  Main handler for incoming requests

    15 *

    16 */

    17 

    18 #ifndef C_LEGACYMODEMPLUGIN_H

    19 #define C_LEGACYMODEMPLUGIN_H

    20 

    21 #include <atextpluginbase.h>

    22 

    23 class CLegacyModemPlugin;

    24 

    25 /** Character types: carriage return, line feed or backspace */

    26 enum TCharacterTypes

    27     {

    28     ECharTypeCR,  // Carriage return

    29     ECharTypeLF,  // Line feed

    30     ECharTypeBS   // Backspace

    31     };

    32 

    33 /** Type of modes (quiet, verbose) */

    34 enum TModeTypes

    35     {

    36     EModeTypeQuiet,   // Quiet mode

    37     EModeTypeVerbose  // Verbose mode

    38     };

    39 

    40 /**  Handler types for the four types */

    41 enum TCmdHandlerType

    42     {

    43     ECmdHandlerTypeUndefined = KErrNotFound,

    44     ECmdHandlerTypeBase      = 0x01,  // For command "AT+COMMAND"

    45     ECmdHandlerTypeSet       = 0x02,  // For command "AT+COMMAND="

    46     ECmdHandlerTypeRead      = 0x04,  // For command "AT+COMMAND?"

    47     ECmdHandlerTypeTest      = 0x08,  // For command "AT+COMMAND=?"

    48     };

    49 

    50 /**

    51  *  Class for common AT command handler interface

    52  *

    53  *  @since S60 v5.0

    54  */

    55 NONSHARABLE_CLASS( CLegacyModemPluginBase )

    56     {

    57 

    58 public:

    59 

    60     virtual ~CLegacyModemPluginBase() {};

    61 

    62     /**

    63      * Reports the support status of an AT command. This is a synchronous API.

    64      *

    65      * @param aCmd The AT command. Its format may vary depending on the

    66      *             specification. E.g. in BT HFP case, the command may contain

    67      *             a character carriage return (<cr>) in the end.

    68      * @return ETrue if the command is supported; EFalse otherwise.

    69      */

    70     virtual TBool IsCommandSupported( const TDesC8& aCmd ) = 0;

    71 

    72     /**

    73      * Handles an AT command. Cancelling of the pending request is done by

    74      * HandleCommandCancel(). The implementation in the extension plugin should

    75      * be asynchronous.

    76      *

    77      * The extension plugin which accepts this command is responsible to supply

    78      * the result codes and response and to format result codes properly, e.g.

    79      * in BT HFP case, the format should be <cr><lf><result code><cr><lf>

    80      *

    81      * After an extension plugin has handled or decided to reject the given AT

    82      * command, it must inform ATEXT by HandleCommandCompleted() with a proper

    83      * error code.

    84      *

    85      * @since S60 5.0

    86      * @param aCmd The AT command to be handled. Its format may vary depending

    87      *             on the specification. E.g. in BT HFP case, the command may

    88      *             contain a character carriage return (<cr>) in the end.

    89      * @param aReply When passed in, contains the built in answer filled by

    90      *               ATEXT if it is not empty; when command handling completes

    91      *               successfully, contains the result codes and responses to

    92      *               this command; Its ownership always belongs to ATEXT, plugin

    93      *               may reallocate its space when needed.

    94      * @param aReplyNeeded Reply needed if ETrue, no reply otherwise. If EFalse,

    95      *                     the aReply must not contain the reply, otherwise it

    96      *                     must contain verbose or numeric reply (ATV0/1) or an

    97      *                     empty string reply (with ATQ).

    98      * @return None

    99      */

   100     virtual void HandleCommand( const TDesC8& aCmd,

   101                                 RBuf8& aReply,

   102                                 TBool aReplyNeeded ) = 0;

   103 

   104     /**

   105      * Cancels a pending HandleCommand request.

   106      *

   107      * @since S60 5.0

   108      * @return None

   109      */

   110     virtual void HandleCommandCancel() = 0;

   111 

   112     };

   113 

   114 /**

   115  *  Class for accessing plugin information and common functionality

   116  *

   117  *  @since S60 v5.0

   118  */

   119 NONSHARABLE_CLASS( MLegacyModemPlugin )

   120     {

   121 

   122 public:

   123 

   124     /**

   125      * Creates an AT command reply based on the reply type and completes the

   126      * request to ATEXT. Uses iReplyBuffer for reply storage.

   127      *

   128      * @since S60 5.0

   129      * @param aReplyType Type of reply

   130      * @param aSrcBuffer Source buffer; used only if aReplyType is EReplyTypeOther

   131      * @param aError Completion code. If not KErrNone then other arguments are

   132      *               ignored and the request is completed to ATEXT with

   133      *               EReplyTypeUndefined.

   134      * @return None

   135      */

   136     virtual TInt CreateReplyAndComplete( TATExtensionReplyType aReplyType,

   137                                          const TDesC8& aSrcBuffer=KNullDesC8,

   138                                          TInt aError=KErrNone ) = 0;

   139 

   140     /**

   141      * Creates a buffer for "OK" or "ERROR" reply based on the line settings

   142      *

   143      * @since S60 5.0

   144      * @param aReplyBuffer Destination buffer for the created reply

   145      * @param aOkReply ETrue if "OK" reply needed,

   146      *                 EFalse if "ERROR" reply needed

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

   148      */

   149     virtual TInt CreateOkOrErrorReply( RBuf8& aReplyBuffer,

   150                                        TBool aOkReply ) = 0;

   151 

   152     /**

   153      * Checks if the command is a base, set, read or test type of command

   154      *

   155      * @since S60 5.0

   156      * @param aCmdBase Base part of the command to check

   157      * @param aCmdFull Full command to check

   158      * @return Type of command

   159      */

   160     virtual TCmdHandlerType CheckCommandType( const TDesC8& aCmdBase,

   161                                               const TDesC8& aCmdFull ) = 0;

   162 

   163     };

   164 

   165 /**

   166  *  Class for selecting handlers for different AT commands

   167  *

   168  *  @since S60 v5.0

   169  */

   170 NONSHARABLE_CLASS( CLegacyModemPlugin ) : public CATExtPluginBase,

   171                                           public MLegacyModemPlugin

   172     {

   173 

   174 public:

   175 

   176     /**

   177      * Two-phased constructor.

   178      * @return Instance of self

   179      */

   180     static CLegacyModemPlugin* NewL();

   181 

   182     /**

   183     * Destructor.

   184     */

   185     virtual ~CLegacyModemPlugin();

   186 

   187 private:

   188 

   189     CLegacyModemPlugin();

   190 

   191     void ConstructL();

   192 

   193     /**

   194      * Reports connection identifier name to the extension plugin.

   195      *

   196      * @since S60 5.0

   197      * @param aName Connection identifier name

   198      * @return None

   199      */

   200     void ReportConnectionName( const TDesC8& aName );

   201 

   202     /**

   203      * Reports the support status of an AT command. This is a synchronous API.

   204      *

   205      * @param aCmd The AT command. Its format may vary depending on the

   206      *             specification. E.g. in BT HFP case, the command may contain

   207      *             a character carriage return (<cr>) in the end.

   208      * @return ETrue if the command is supported; EFalse otherwise.

   209      */

   210     TBool IsCommandSupported( const TDesC8& aCmd );

   211 

   212     /**

   213      * Handles an AT command. Cancelling of the pending request is done by

   214      * HandleCommandCancel(). The implementation in the extension plugin should

   215      * be asynchronous.

   216      *

   217      * The extension plugin which accepts this command is responsible to supply

   218      * the result codes and response and to format result codes properly, e.g.

   219      * in BT HFP case, the format should be <cr><lf><result code><cr><lf>

   220      *

   221      * After an extension plugin has handled or decided to reject the given AT

   222      * command, it must inform ATEXT by HandleCommandCompleted() with a proper

   223      * error code.

   224      *

   225      * @since S60 5.0

   226      * @param aCmd The AT command to be handled. Its format may vary depending

   227      *             on the specification. E.g. in BT HFP case, the command may

   228      *             contain a character carriage return (<cr>) in the end.

   229      * @param aReply When passed in, contains the built in answer filled by

   230      *               ATEXT if it is not empty; when command handling completes

   231      *               successfully, contains the result codes and responses to

   232      *               this command; Its ownership always belongs to ATEXT, plugin

   233      *               may reallocate its space when needed.

   234      * @param aReplyNeeded Reply needed if ETrue, no reply otherwise. If EFalse,

   235      *                     the aReply must not contain the reply, otherwise it

   236      *                     must contain verbose or numeric reply (ATV0/1) or an

   237      *                     empty string reply (with ATQ).

   238      * @return None

   239      */

   240     void HandleCommand( const TDesC8& aCmd, RBuf8& aReply, TBool aReplyNeeded );

   241 

   242     /**

   243      * Cancels a pending HandleCommand request.

   244      *

   245      * @since S60 5.0

   246      * @return None

   247      */

   248     void HandleCommandCancel();

   249 

   250     /**

   251      * Next reply part's length.

   252      * The value must be equal or less than KDefaultCmdBufLength.

   253      * When the reply from this method is zero, ATEXT stops calling

   254      * GetNextPartOfReply().

   255      *

   256      * @since S60 5.0

   257      * @return Next reply part's length if zero or positive

   258      */

   259     TInt NextReplyPartLength();

   260 

   261     /**

   262      * Gets the next part of reply initially set by HandleCommandComplete().

   263      * Length of aNextReply must be equal or less than KDefaultCmdBufLength.

   264      *

   265      * @since S60 5.0

   266      * @param aNextReply Next reply

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

   268      */

   269     TInt GetNextPartOfReply( RBuf8& aNextReply );

   270 

   271     /**

   272      * Receives unsolicited results. Cancelling of the pending request is done

   273      * by ReceiveUnsolicitedResultCancel(). The implementation in the extension

   274      * plugin should be asynchronous.

   275      *

   276      * @since S60 5.0

   277      * @return None

   278      */

   279     void ReceiveUnsolicitedResult();

   280 

   281     /**

   282      * Cancels a pending ReceiveUnsolicitedResult request.

   283      *

   284      * @since S60 5.0

   285      * @return None

   286      */

   287     void ReceiveUnsolicitedResultCancel();

   288 

   289     /**

   290      * Reports NVRAM status change to the plugins.

   291      *

   292      * @since S60 5.0

   293      * @param aNvram New NVRAM status. Each call of this function is a result

   294      *               of DUN extracting the form notified by

   295      *               CATExtCommonBase::SendNvramStatusChange(). Each of the

   296      *               settings from SendNvramStatusChange() is separated to

   297      *               one call of ReportNvramStatusChange().

   298      * @return None

   299      */

   300     void ReportNvramStatusChange( const TDesC8& aNvram );

   301 

   302     /**

   303      * Reports about external handle command error condition.

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

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

   306      * Example: in command line "AT+TEST;ATDT1234" was given. "AT+TEST" returns

   307      * "OK" and "ATDT" returns "CONNECT". Because "OK" and "CONNECT" are

   308      * different reply types the condition is "ERROR" and DUN ends processing.

   309      * This solution keeps the pointer to the last AT command handling plugin

   310      * inside ATEXT and calls this function there to report the error.

   311      * It is to be noted that HandleCommandCancel() is not sufficient to stop

   312      * the processing as the command handling has already finished.

   313      *

   314      * @since S60 5.0

   315      * @return None

   316      */

   317     void ReportExternalHandleCommandError();

   318 

   319     /**

   320      * Creates part of reply from the global reply buffer to the destination

   321      * buffer. Used with APIs which need the next part of reply in multipart

   322      * reply requests.

   323      *

   324      * @since S60 5.0

   325      * @param aDstBuffer Destination buffer; the next part of reply is stored to

   326      *                   this buffer.

   327      * @return None

   328      */

   329     TInt CreatePartOfReply( RBuf8& aDstBuffer );

   330 

   331     /**

   332      * Appends one parameter to array for GetParameterArray()

   333      *

   334      * @since S60 5.0

   335      * @param aParams Array of supported commands

   336      * @param aStartIndex Start index for the parameter to be added

   337      * @param aEndIndex End index for the parameter to be added

   338      * @return None

   339      */

   340     void AppendOneParameterLC( RPointerArray<HBufC8>& aParams,

   341                                TInt& aStartIndex,

   342                                TInt aEndIndex );

   343 

   344 // from base class MLegacyModemPlugin

   345 

   346     /**

   347      * From MLegacyModemPlugin.

   348      * Creates an AT command reply based on the reply type and completes the

   349      * request to ATEXT. Uses iReplyBuffer for reply storage.

   350      *

   351      * @since S60 5.0

   352      * @param aReplyType Type of reply

   353      * @param aSrcBuffer Source buffer; used only if aReplyType is EReplyTypeOther

   354      * @param aError Completion code. If not KErrNone then other arguments are

   355      *               ignored and the request is completed to ATEXT with

   356      *               EReplyTypeUndefined.

   357      * @return None

   358      */

   359     TInt CreateReplyAndComplete( TATExtensionReplyType aReplyType,

   360                                  const TDesC8& aSrcBuffer=KNullDesC8,

   361                                  TInt aError=KErrNone );

   362 

   363     /**

   364      * From MLegacyModemPlugin.

   365      * Creates a buffer for "OK" or "ERROR" reply based on the line settings

   366      *

   367      * @since S60 5.0

   368      * @param aReplyBuffer Destination buffer for the created reply

   369      * @param aOkReply ETrue if "OK" reply needed,

   370      *                 EFalse if "ERROR" reply needed

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

   372      */

   373     TInt CreateOkOrErrorReply( RBuf8& aReplyBuffer,

   374                                TBool aOkReply );

   375 

   376     /**

   377      * From MLegacyModemPlugin.

   378      * Checks if the command is a base, set, read or test type of command

   379      *

   380      * @since S60 5.0

   381      * @param aCmdBase Base part of the command to check

   382      * @param aCmdFull Full command to check

   383      * @return Type of command

   384      */

   385     TCmdHandlerType CheckCommandType( const TDesC8& aCmdBase,

   386                                       const TDesC8& aCmdFull );

   387 

   388 private:  // data

   389 

   390     /**

   391      * AT commands handler array. Used for mapping HandleCommand() to

   392      * IsCommandSupported() and to limit the number of string comparisons.

   393      */

   394     RPointerArray<CLegacyModemPluginBase> iHandlers;

   395 

   396     /**

   397      * Current AT command handler in iHandlers.

   398      * Used when IsCommandSupported() detects a matching handler class.

   399      */

   400     CLegacyModemPluginBase* iHandler;

   401 

   402     /**

   403      * Buffer for handle command's command

   404      * Not own.

   405      */

   406     const TDesC8* iHcCmd;

   407 

   408     /**

   409      * Buffer for handle command reply

   410      * Not own.

   411      */

   412     RBuf8* iHcReply;

   413 

   414     /**

   415      * Global reply buffer for the AT command replies

   416      */

   417     RBuf8 iReplyBuffer;

   418 

   419     };

   420 

   421 #endif  // C_LEGACYMODEMPLUGIN_H