1 /*

     2 * Copyright (c) 2010 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_LCCUSTOMPLUGIN_H

    19 #define C_LCCUSTOMPLUGIN_H

    20 

    21 #include <atextpluginbase.h>

    22 

    23 class CLcCustomPlugin;

    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 /**  Detected commands */

    51 enum TDetectedCmd

    52     {

    53     EDetectedCmdUndefined,

    54     EDetectedCmdCLAC  // For command "AT+CLAC"

    55     };

    56 

    57 /**

    58  *  Class for common AT command handler interface

    59  *

    60  *  @since S60 v5.0

    61  */

    62 NONSHARABLE_CLASS( CLcCustomPluginBase )

    63     {

    64 

    65 public:

    66 

    67     virtual ~CLcCustomPluginBase() {};

    68 

    69     /**

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

    71      *

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

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

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

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

    76      */

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

    78 

    79     /**

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

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

    82      * be asynchronous.

    83      *

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

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

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

    87      *

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

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

    90      * error code.

    91      *

    92      * @since S60 5.0

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

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

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

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

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

    98      *               successfully, contains the result codes and responses to

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

   100      *               may reallocate its space when needed.

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

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

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

   104      *                     empty string reply (with ATQ).

   105      * @return None

   106      */

   107     virtual void HandleCommand( const TDesC8& aCmd,

   108                                 RBuf8& aReply,

   109                                 TBool aReplyNeeded ) = 0;

   110 

   111     /**

   112      * Cancels a pending HandleCommand request.

   113      *

   114      * @since S60 5.0

   115      * @return None

   116      */

   117     virtual void HandleCommandCancel() = 0;

   118 

   119     };

   120 

   121 /**

   122  *  Class for accessing plugin information and common functionality

   123  *

   124  *  @since S60 v5.0

   125  */

   126 NONSHARABLE_CLASS( MLcCustomPlugin )

   127     {

   128 

   129 public:

   130 

   131     /**

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

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

   134      *

   135      * @since S60 5.0

   136      * @param aReplyType Type of reply

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

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

   139      *               ignored and the request is completed to ATEXT with

   140      *               EReplyTypeUndefined.

   141      * @return None

   142      */

   143     virtual TInt CreateReplyAndComplete( TATExtensionReplyType aReplyType,

   144                                          const TDesC8& aSrcBuffer=KNullDesC8,

   145                                          TInt aError=KErrNone ) = 0;

   146 

   147     /**

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

   149      *

   150      * @since S60 5.0

   151      * @param aReplyBuffer Destination buffer for the created reply

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

   153      *                 EFalse if "ERROR" reply needed

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

   155      */

   156     virtual TInt CreateOkOrErrorReply( RBuf8& aReplyBuffer,

   157                                        TBool aOkReply ) = 0;

   158 

   159     /**

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

   161      *

   162      * @since TB9.2

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

   164      * @param aCmdFull Full command to check

   165      * @return Type of command

   166      */

   167     virtual TCmdHandlerType CheckCommandType( const TDesC8& aCmdBase,

   168                                               const TDesC8& aCmdFull ) = 0;

   169 

   170     /**

   171      * Returns the array of supported commands

   172      *

   173      * @since S60 5.0

   174      * @param aCmd Array of supported commands

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

   176      */

   177     virtual TInt GetSupportedCommands( RPointerArray<HBufC8>& aCmds ) = 0;

   178 

   179     /**

   180      * Returns plugin's character value settings (from CATExtPluginBase)

   181      *

   182      * @since S60 5.0

   183      * @param aCharType Character's type

   184      * @param aChar Character's value matching aCharType

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

   186      */

   187     virtual TInt GetCharacterValue( TCharacterTypes aCharType, TChar& aChar ) = 0;

   188 

   189     /**

   190      * Returns plugin's mode value settings (from CATExtPluginBase)

   191      *

   192      * @since S60 5.0

   193      * @param aModeType Mode type

   194      * @param aMode Mode value matching aModeType

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

   196      */

   197     virtual TInt GetModeValue( TModeTypes aModeType, TBool& aMode ) = 0;

   198 

   199     };

   200 

   201 /**

   202  *  Class for selecting handlers for different AT commands

   203  *

   204  *  @since S60 v5.0

   205  */

   206 NONSHARABLE_CLASS( CLcCustomPlugin ) : public CATExtPluginBase,

   207                                        public MLcCustomPlugin

   208     {

   209 

   210 public:

   211 

   212     /**

   213      * Two-phased constructor.

   214      * @return Instance of self

   215      */

   216     static CLcCustomPlugin* NewL();

   217 

   218     /**

   219     * Destructor.

   220     */

   221     virtual ~CLcCustomPlugin();

   222 

   223 private:

   224 

   225     CLcCustomPlugin();

   226 

   227     void ConstructL();

   228 

   229     /**

   230      * Reports connection identifier name to the extension plugin.

   231      *

   232      * @since S60 5.0

   233      * @param aName Connection identifier name

   234      * @return None

   235      */

   236     void ReportConnectionName( const TDesC8& aName );

   237 

   238     /**

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

   240      *

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

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

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

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

   245      */

   246     TBool IsCommandSupported( const TDesC8& aCmd );

   247 

   248     /**

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

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

   251      * be asynchronous.

   252      *

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

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

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

   256      *

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

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

   259      * error code.

   260      *

   261      * @since S60 5.0

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

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

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

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

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

   267      *               successfully, contains the result codes and responses to

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

   269      *               may reallocate its space when needed.

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

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

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

   273      *                     empty string reply (with ATQ).

   274      * @return None

   275      */

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

   277 

   278     /**

   279      * Cancels a pending HandleCommand request.

   280      *

   281      * @since S60 5.0

   282      * @return None

   283      */

   284     void HandleCommandCancel();

   285 

   286     /**

   287      * Next reply part's length.

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

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

   290      * GetNextPartOfReply().

   291      *

   292      * @since S60 5.0

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

   294      */

   295     TInt NextReplyPartLength();

   296 

   297     /**

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

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

   300      *

   301      * @since S60 5.0

   302      * @param aNextReply Next reply

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

   304      */

   305     TInt GetNextPartOfReply( RBuf8& aNextReply );

   306 

   307     /**

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

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

   310      * plugin should be asynchronous.

   311      *

   312      * @since S60 5.0

   313      * @return None

   314      */

   315     void ReceiveUnsolicitedResult();

   316 

   317     /**

   318      * Cancels a pending ReceiveUnsolicitedResult request.

   319      *

   320      * @since S60 5.0

   321      * @return None

   322      */

   323     void ReceiveUnsolicitedResultCancel();

   324 

   325     /**

   326      * Reports NVRAM status change to the plugins.

   327      *

   328      * @since S60 5.0

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

   330      *               of DUN extracting the form notified by

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

   332      *               settings from SendNvramStatusChange() is separated to

   333      *               one call of ReportNvramStatusChange().

   334      * @return None

   335      */

   336     void ReportNvramStatusChange( const TDesC8& aNvram );

   337 

   338     /**

   339      * Reports about external handle command error condition.

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

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

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

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

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

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

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

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

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

   349      *

   350      * @since S60 5.0

   351      * @return None

   352      */

   353     void ReportExternalHandleCommandError();

   354 

   355     /**

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

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

   358      * reply requests.

   359      *

   360      * @since S60 5.0

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

   362      *                   this buffer.

   363      * @return None

   364      */

   365     TInt CreatePartOfReply( RBuf8& aDstBuffer );

   366 

   367 // from base class MLcCustomPlugin

   368 

   369     /**

   370      * From MLcCustomPlugin.

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

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

   373      *

   374      * @since S60 5.0

   375      * @param aReplyType Type of reply

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

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

   378      *               ignored and the request is completed to ATEXT with

   379      *               EReplyTypeUndefined.

   380      * @return None

   381      */

   382     TInt CreateReplyAndComplete( TATExtensionReplyType aReplyType,

   383                                  const TDesC8& aSrcBuffer=KNullDesC8,

   384                                  TInt aError=KErrNone );

   385 

   386     /**

   387      * From MLcCustomPlugin.

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

   389      *

   390      * @since S60 5.0

   391      * @param aReplyBuffer Destination buffer for the created reply

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

   393      *                 EFalse if "ERROR" reply needed

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

   395      */

   396     TInt CreateOkOrErrorReply( RBuf8& aReplyBuffer,

   397                                TBool aOkReply );

   398 

   399     /**

   400      * From MLcCustomPlugin.

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

   402      *

   403      * @since S60 5.0

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

   405      * @param aCmdFull Full command to check

   406      * @return Type of command

   407      */

   408     TCmdHandlerType CheckCommandType( const TDesC8& aCmdBase,

   409                                       const TDesC8& aCmdFull );

   410 

   411     /**

   412      * From MLcCustomPlugin.

   413      * Returns the array of supported commands

   414      *

   415      * @since S60 5.0

   416      * @param aCmd Array of supported commands

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

   418      */

   419     TInt GetSupportedCommands( RPointerArray<HBufC8>& aCmds );

   420 

   421     /**

   422      * From MLcCustomPlugin.

   423      * Returns plugin's character value settings (from CATExtPluginBase)

   424      *

   425      * @since S60 5.0

   426      * @param aCharType Character's type

   427      * @param aChar Character's value matching aCharType

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

   429      */

   430     TInt GetCharacterValue( TCharacterTypes aCharType, TChar& aChar );

   431 

   432     /**

   433      * From MLcCustomPlugin.

   434      * Returns plugin's mode value settings (from CATExtPluginBase)

   435      *

   436      * @since S60 5.0

   437      * @param aModeType Mode type

   438      * @param aMode Mode value matching aModeType

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

   440      */

   441     TInt GetModeValue( TModeTypes aModeType, TBool& aMode );

   442 

   443 private:  // data

   444 

   445     /**

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

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

   448      */

   449     RPointerArray<CLcCustomPluginBase> iHandlers;

   450 

   451     /**

   452      * Current AT command handler in iHandlers.

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

   454      */

   455     CLcCustomPluginBase* iHandler;

   456 

   457     /**

   458      * Buffer for handle command's command

   459      * Not own.

   460      */

   461     const TDesC8* iHcCmd;

   462 

   463     /**

   464      * Buffer for handle command reply

   465      * Not own.

   466      */

   467     RBuf8* iHcReply;

   468 

   469     /**

   470      * Global reply buffer for the AT command replies

   471      */

   472     RBuf8 iReplyBuffer;

   473 

   474     };

   475 

   476 #endif  // C_LCCUSTOMPLUGIN_H