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_MODEMATPLUGIN_H

    20 #define C_MODEMATPLUGIN_H

    21 

    22 #include <atextpluginbase.h>

    23 #include "cmdpluginobserver.h" 

    24 

    25 

    26 /**

    27  *  Class for common AT command handler interface

    28  *

    29  *  @since S60 TB9.2 

    30  */

    31 NONSHARABLE_CLASS( CATCommandHandlerBase )

    32     {

    33 

    34 public:

    35 

    36     virtual ~CATCommandHandlerBase() {};

    37 

    38     /**

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

    40      *

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

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

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

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

    45      */

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

    47 

    48     /**

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

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

    51      * be asynchronous.

    52      *

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

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

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

    56      *

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

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

    59      * error code.

    60      *

    61      * @since S60 TB9.2

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

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

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

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

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

    67      *               successfully, contains the result codes and responses to

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

    69      *               may reallocate its space when needed.

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

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

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

    73      *                     empty string reply (with ATQ).

    74      * @return None

    75      */

    76     virtual void HandleCommand( const TDesC8& aCmd,

    77                                 RBuf8& aReply,

    78                                 TBool aReplyNeeded ) = 0;

    79 

    80     /**

    81      * Cancels a pending HandleCommand request.

    82      *

    83      * @since S60 TB9.2

    84      * @return None

    85      */

    86     virtual void HandleCommandCancel() = 0;

    87 

    88     };

    89 

    90 

    91 /**

    92  *  Class for selecting handlers for different AT commands

    93  *

    94  *  @since TB9.2 

    95  */

    96 NONSHARABLE_CLASS( CModemAtPlugin ) : public CATExtPluginBase, public MCmdPluginObserver 

    97     {

    98 

    99 public:

   100 

   101     /**

   102      * Two-phased constructor.

   103      * @return Instance of self

   104      */

   105     static CModemAtPlugin* NewL();

   106 

   107     /**

   108     * Destructor.

   109     */

   110     virtual ~CModemAtPlugin();

   111 

   112 private:

   113 

   114     CModemAtPlugin();

   115 

   116     void ConstructL();

   117 

   118     /**

   119      * Reports connection identifier name to the extension plugin.

   120      *

   121      * @since TB9.2 

   122      * @param aName Connection identifier name

   123      * @return None

   124      */

   125     void ReportConnectionName( const TDesC8& aName );

   126 

   127     /**

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

   129      *

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

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

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

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

   134      */

   135     TBool IsCommandSupported( const TDesC8& aCmd );

   136 

   137     /**

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

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

   140      * be asynchronous.

   141      *

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

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

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

   145      *

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

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

   148      * error code.

   149      *

   150      * @since TB9.2 

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

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

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

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

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

   156      *               successfully, contains the result codes and responses to

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

   158      *               may reallocate its space when needed.

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

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

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

   162      *                     empty string reply (with ATQ).

   163      * @return None

   164      */

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

   166 

   167     /**

   168      * Cancels a pending HandleCommand request.

   169      *

   170      * @since TB9.2 

   171      * @return None

   172      */

   173     void HandleCommandCancel();

   174 

   175     /**

   176      * Next reply part's length.

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

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

   179      * GetNextPartOfReply().

   180      *

   181      * @since TB9.2 

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

   183      */

   184     TInt NextReplyPartLength();

   185 

   186     /**

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

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

   189      *

   190      * @since TB9.2 

   191      * @param aNextReply Next reply

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

   193      */

   194     TInt GetNextPartOfReply( RBuf8& aNextReply );

   195 

   196     /**

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

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

   199      * plugin should be asynchronous.

   200      *

   201      * @since TB9.2 

   202      * @return None

   203      */

   204     void ReceiveUnsolicitedResult();

   205 

   206     /**

   207      * Cancels a pending ReceiveUnsolicitedResult request.

   208      *

   209      * @since TB9.2 

   210      * @return None

   211      */

   212     void ReceiveUnsolicitedResultCancel();

   213 

   214     /**

   215      * Reports NVRAM status change to the plugins.

   216      *

   217      * @since TB9.2 

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

   219      *               of DUN extracting the form notified by

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

   221      *               settings from SendNvramStatusChange() is separated to

   222      *               one call of ReportNvramStatusChange().

   223      * @return None

   224      */

   225     void ReportNvramStatusChange( const TDesC8& aNvram );

   226 

   227     /**

   228      * Reports about external handle command error condition.

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

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

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

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

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

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

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

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

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

   238      *

   239      * @since TB9.2 

   240      * @return None

   241      */

   242     void ReportExternalHandleCommandError();

   243 

   244     /**

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

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

   247      * reply requests.

   248      *

   249      * @since TB9.2 

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

   251      *                   this buffer.

   252      * @return None

   253      */

   254     TInt CreatePartOfReply( RBuf8& aDstBuffer );

   255 

   256 // from base class MCmdPluginObserver

   257 

   258     /**

   259      * From MCmdPluginObserver.

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

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

   262      *

   263      * @since TB9.2 

   264      * @param aReplyType Type of reply

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

   266      *                   AT command reply

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

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

   269      *               ignored and the request is completed to ATEXT with

   270      *               EReplyTypeUndefined.

   271      * @return None

   272      */

   273     TInt CreateReplyAndComplete( TATExtensionReplyType aReplyType,

   274                                  const TDesC8& aSrcBuffer=KNullDesC8,

   275                                  TInt aError=KErrNone );

   276 

   277     /**

   278      * From MCmdPluginObserver.

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

   280      *

   281      * @since TB9.2 

   282      * @param aReplyBuffer Destination buffer for the created reply

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

   284      *                 EFalse if "ERROR" reply needed

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

   286      */

   287     TInt CreateOkOrErrorReply( RBuf8& aReplyBuffer,

   288                                TBool aOkReply );

   289 

   290     /**

   291      * From MCmdPluginObserver.

   292      * Returns the array of supported commands

   293      *

   294      * @since TB9.2 

   295      * @param aCmd Array of supported commands

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

   297      */

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

   299 

   300     /**

   301      * From MCmdPluginObserver.

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

   303      *

   304      * @since TB9.2 

   305      * @param aCharType Character's type

   306      * @param aChar Character's value matching aCharType

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

   308      */

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

   310 

   311     /**

   312      * From MCmdPluginObserver.

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

   314      *

   315      * @since TB9.2 

   316      * @param aModeType Mode type

   317      * @param aMode Mode value matching aModeType

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

   319      */

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

   321 

   322 private:  // data

   323 

   324     /**

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

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

   327      */

   328     RPointerArray<CATCommandHandlerBase> iHandlers;

   329 

   330     /**

   331      * Current AT command handler in iHandlers.

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

   333      */

   334     CATCommandHandlerBase* iHandler;

   335 

   336     /**

   337      * Buffer for handle command's command

   338      * Not own.

   339      */

   340     const TDesC8* iHcCmd;

   341 

   342     /**

   343      * Buffer for handle command reply

   344      * Not own.

   345      */

   346     RBuf8* iHcReply;

   347 

   348 

   349     /**

   350      * Global reply buffer for the AT command replies

   351      */

   352     RBuf8 iReplyBuffer;

   353 

   354     };

   355 

   356 #endif  // C_MODEMPLUGIN_H