atext/plugins/legacymodemplugin/inc/legacymodemplugin.h
branchRCL_3
changeset 12 9b6d3ca0c601
equal deleted inserted replaced
11:20fda83a6398 12:9b6d3ca0c601
       
     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