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 

    19 #ifndef C_LCCUSTOMPLUGIN_H

    20 #define C_LCCUSTOMPLUGIN_H

    21 

    22 #include <atextpluginbase.h>

    23 

    24 class CLcCustomPlugin;

    25 

    26 enum TCharacterTypes

    27     {

    28     ECharTypeCR,  // Carriage return

    29     ECharTypeLF,  // Line feed

    30     ECharTypeBS   // Backspace

    31     };

    32 

    33 enum TModeTypes

    34     {

    35     EModeTypeQuiet,   // Quiet mode

    36     EModeTypeVerbose  // Verbose mode

    37     };

    38 

    39 /**

    40  *  Class for common AT command handler interface

    41  *

    42  *  @since S60 v5.0

    43  */

    44 NONSHARABLE_CLASS( CLcCustomPluginBase )

    45     {

    46 

    47 public:

    48 

    49     virtual ~CLcCustomPluginBase() {};

    50 

    51     /**

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

    53      *

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

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

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

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

    58      */

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

    60 

    61     /**

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

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

    64      * be asynchronous.

    65      *

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

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

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

    69      *

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

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

    72      * error code.

    73      *

    74      * @since S60 5.0

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

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

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

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

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

    80      *               successfully, contains the result codes and responses to

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

    82      *               may reallocate its space when needed.

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

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

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

    86      *                     empty string reply (with ATQ).

    87      * @return None

    88      */

    89     virtual void HandleCommand( const TDesC8& aCmd,

    90                                 RBuf8& aReply,

    91                                 TBool aReplyNeeded ) = 0;

    92 

    93     /**

    94      * Cancels a pending HandleCommand request.

    95      *

    96      * @since S60 5.0

    97      * @return None

    98      */

    99     virtual void HandleCommandCancel() = 0;

   100 

   101     };

   102 

   103 /**

   104  *  Class for accessing plugin information and common functionality

   105  *

   106  *  @since S60 v5.0

   107  */

   108 NONSHARABLE_CLASS( MLcCustomPlugin )

   109     {

   110 

   111 public:

   112 

   113     /**

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

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

   116      *

   117      * @since S60 5.0

   118      * @param aReplyType Type of reply

   119      * @param aDstBuffer Destination buffer; used for the API requiring the

   120      *                   AT command reply

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

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

   123      *               ignored and the request is completed to ATEXT with

   124      *               EReplyTypeUndefined.

   125      * @return None

   126      */

   127     virtual TInt CreateReplyAndComplete( TATExtensionReplyType aReplyType,

   128                                          RBuf8& aDstBuffer,

   129                                          const TDesC8& aSrcBuffer=KNullDesC8,

   130                                          TInt aError=KErrNone ) = 0;

   131 

   132     /**

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

   134      *

   135      * @since S60 5.0

   136      * @param aReplyBuffer Destination buffer for the created reply

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

   138      *                 EFalse if "ERROR" reply needed

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

   140      */

   141     virtual TInt CreateOkOrErrorReply( RBuf8& aReplyBuffer,

   142                                        TBool aOkReply ) = 0;

   143 

   144     /**

   145      * Returns the array of supported commands

   146      *

   147      * @since S60 5.0

   148      * @param aCmd Array of supported commands

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

   150      */

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

   152 

   153     /**

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

   155      *

   156      * @since S60 5.0

   157      * @param aCharType Character's type

   158      * @param aChar Character's value matching aCharType

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

   160      */

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

   162 

   163     /**

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

   165      *

   166      * @since S60 5.0

   167      * @param aModeType Mode type

   168      * @param aMode Mode value matching aModeType

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

   170      */

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

   172 

   173     };

   174 

   175 /**

   176  *  Class for selecting handlers for different AT commands

   177  *

   178  *  @since S60 v5.0

   179  */

   180 NONSHARABLE_CLASS( CLcCustomPlugin ) : public CATExtPluginBase,

   181                                        public MLcCustomPlugin

   182     {

   183 

   184 public:

   185 

   186     /**

   187      * Two-phased constructor.

   188      * @return Instance of self

   189      */

   190     static CLcCustomPlugin* NewL();

   191 

   192     /**

   193     * Destructor.

   194     */

   195     virtual ~CLcCustomPlugin();

   196 

   197 private:

   198 

   199     CLcCustomPlugin();

   200 

   201     void ConstructL();

   202 

   203     /**

   204      * Reports connection identifier name to the extension plugin.

   205      *

   206      * @since S60 5.0

   207      * @param aName Connection identifier name

   208      * @return None

   209      */

   210     void ReportConnectionName( const TDesC8& aName );

   211 

   212     /**

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

   214      *

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

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

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

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

   219      */

   220     TBool IsCommandSupported( const TDesC8& aCmd );

   221 

   222     /**

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

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

   225      * be asynchronous.

   226      *

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

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

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

   230      *

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

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

   233      * error code.

   234      *

   235      * @since S60 5.0

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

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

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

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

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

   241      *               successfully, contains the result codes and responses to

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

   243      *               may reallocate its space when needed.

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

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

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

   247      *                     empty string reply (with ATQ).

   248      * @return None

   249      */

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

   251 

   252     /**

   253      * Cancels a pending HandleCommand request.

   254      *

   255      * @since S60 5.0

   256      * @return None

   257      */

   258     void HandleCommandCancel();

   259 

   260     /**

   261      * Next reply part's length.

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

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

   264      * GetNextPartOfReply().

   265      *

   266      * @since S60 5.0

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

   268      */

   269     TInt NextReplyPartLength();

   270 

   271     /**

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

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

   274      *

   275      * @since S60 5.0

   276      * @param aNextReply Next reply

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

   278      */

   279     TInt GetNextPartOfReply( RBuf8& aNextReply );

   280 

   281     /**

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

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

   284      * plugin should be asynchronous.

   285      *

   286      * @since S60 5.0

   287      * @return None

   288      */

   289     void ReceiveUnsolicitedResult();

   290 

   291     /**

   292      * Cancels a pending ReceiveUnsolicitedResult request.

   293      *

   294      * @since S60 5.0

   295      * @return None

   296      */

   297     void ReceiveUnsolicitedResultCancel();

   298 

   299     /**

   300      * Reports NVRAM status change to the plugins.

   301      *

   302      * @since S60 5.0

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

   304      *               of DUN extracting the form notified by

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

   306      *               settings from SendNvramStatusChange() is separated to

   307      *               one call of ReportNvramStatusChange().

   308      * @return None

   309      */

   310     void ReportNvramStatusChange( const TDesC8& aNvram );

   311 

   312     /**

   313      * Reports about external handle command error condition.

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

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

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

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

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

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

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

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

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

   323      *

   324      * @since S60 5.0

   325      * @return None

   326      */

   327     void ReportExternalHandleCommandError();

   328 

   329     /**

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

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

   332      * reply requests.

   333      *

   334      * @since S60 5.0

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

   336      *                   this buffer.

   337      * @return None

   338      */

   339     TInt CreatePartOfReply( RBuf8& aDstBuffer );

   340 

   341 // from base class MLcCustomPlugin

   342 

   343     /**

   344      * From MLcCustomPlugin.

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

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

   347      *

   348      * @since S60 5.0

   349      * @param aReplyType Type of reply

   350      * @param aDstBuffer Destination buffer; used for the API requiring the

   351      *                   AT command reply

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

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

   354      *               ignored and the request is completed to ATEXT with

   355      *               EReplyTypeUndefined.

   356      * @return None

   357      */

   358     TInt CreateReplyAndComplete( TATExtensionReplyType aReplyType,

   359                                  RBuf8& aDstBuffer,

   360                                  const TDesC8& aSrcBuffer=KNullDesC8,

   361                                  TInt aError=KErrNone );

   362 

   363     /**

   364      * From MLcCustomPlugin.

   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 MLcCustomPlugin.

   378      * Returns the array of supported commands

   379      *

   380      * @since S60 5.0

   381      * @param aCmd Array of supported commands

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

   383      */

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

   385 

   386     /**

   387      * From MLcCustomPlugin.

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

   389      *

   390      * @since S60 5.0

   391      * @param aCharType Character's type

   392      * @param aChar Character's value matching aCharType

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

   394      */

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

   396 

   397     /**

   398      * From MLcCustomPlugin.

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

   400      *

   401      * @since S60 5.0

   402      * @param aModeType Mode type

   403      * @param aMode Mode value matching aModeType

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

   405      */

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

   407 

   408 private:  // data

   409 

   410     /**

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

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

   413      */

   414     RPointerArray<CLcCustomPluginBase> iHandlers;

   415 

   416     /**

   417      * Current AT command handler in iHandlers.

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

   419      */

   420     CLcCustomPluginBase* iHandler;

   421 

   422     /**

   423      * Global reply buffer for the AT command replies

   424      */

   425     RBuf8 iReplyBuffer;

   426 

   427     };

   428 

   429 #endif  // C_LCCUSTOMPLUGIN_H