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 the License "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: 

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef ISAKERNELAPI_H

    21 #define ISAKERNELAPI_H

    22 

    23 //  INCLUDES

    24 #include <klib.h>       // For DBase

    25 

    26 // CONSTANTS

    27 // None

    28 

    29 // MACROS

    30 // None

    31 

    32 // DATA TYPES

    33 // None

    34 

    35 // FUNCTION PROTOTYPES

    36 // None

    37 

    38 // FORWARD DECLARATIONS

    39 class DISAKernelChannel;

    40 

    41 // CLASS DECLARATION

    42 

    43 /**

    44 *  Kernel interface for ISA Access Driver.

    45 *

    46 *  @lib IsaKernelAPI

    47 *  @since S_CPR81

    48 */

    49 NONSHARABLE_CLASS( DIsaKernelAPI ) : public DBase

    50 {

    51 

    52 

    53     public:

    54 

    55     /**

    56     * Static constructor. Returns an new instance of the object.

    57     * NOTE! Kern::Fault raised if no free memory left.

    58     */

    59     static IMPORT_C DIsaKernelAPI* NewF();

    60 

    61     /**

    62     * Destructor.

    63     * Cancels any outstanding DFC requests and closes the channel.

    64     */

    65     IMPORT_C ~DIsaKernelAPI();

    66 

    67     /**

    68     * Get a free block for ISI message sending. Block is at least the size

    69     * of the param aSize.

    70     * NOTE! Kern::Fault raised if no free blocks left.

    71     * Preconditions: Channel is succesfully opened.

    72     * Postconditions: Block allocated and reference returned.

    73     * Called in kernel thread context.

    74     * Called with no fastmutex held.

    75     * Called with interrupts enabled.

    76     * Called without kernel lock held.

    77     * @param aSize, minimum size of the buffer.

    78     * @return TDes8&, reference to allocated block.

    79     */

    80     IMPORT_C TDes8& AllocateMsgBlock( const TInt aSize );

    81 

    82     /**

    83     * Get a free block for data message sending. Block is at least the size

    84     * of the param aSize. 

    85     * NOTE! Message allocated with this function must be

    86     * send with DataSend.

    87     * NOTE! Kern::Fault raised if no free blocks left.

    88     * Preconditions: Channel is succesfully opened.

    89     * Postconditions: Block allocated and reference returned.

    90     * Called in kernel thread context.

    91     * Called with no fastmutex held.

    92     * Called with interrupts enabled.

    93     * Called without kernel lock held.

    94     * @param aSize, minimum size of the buffer.

    95     * @return TDes8&, reference to allocated datablock.

    96     */

    97     IMPORT_C TDes8& AllocateDataMsgBlock( const TInt aSize );

    98 

    99     /**

   100     * Closes the channel. If channel is not open does nothing. Cancels any

   101     * outstanding DFC requests.

   102     * Preconditions: Channel is succesfully opened.

   103     * Postconditions: Channel closed and outstanding requests cancelled.

   104     * Called in kernel thread context.

   105     * Called with no fastmutex held.

   106     * Called with interrupts enabled.

   107     * Called without kernel lock held.

   108     * @return None

   109     */

   110     IMPORT_C void Close();

   111 

   112     /**

   113     * Receive message. DFC function given as param

   114     * shall be queued to run when message is received.

   115     * NOTE! After Receive DFC completion, client must deallocate block with

   116     * DeAllocateDataMsgBlock and set the pointer to NULL.

   117     * Preconditions: Channel is succesfully opened.

   118     *                           Parameter aDataMsgBlock must be NULL.

   119     * Postconditions: Receive is pending.

   120     * Kern::Fault will be raised if API can't allocate receive buffer.

   121     * Kern::Fault will be raised if same request is set when it is already pending.

   122     * Called in kernel thread context.

   123     * Called with no fastmutex held.

   124     * Called with interrupts enabled.

   125     * Called without kernel lock held.

   126     * @param aDataMsgBlock, block where received data message is written.

   127     * @param aDfcStatus, updated when DFC is queued. 

   128     *                    KErrNone, succefull

   129     *                    KErrCancel, receive was cancelled client no need to deallocate block get from receive.

   130     * @param aDataReceiveDfc, clients DFC function for receiving message. 

   131     * @return None

   132     */

   133     IMPORT_C void DataReceive( TDes8*& aDataMsgBlock,

   134                                TInt& aDfcStatus,

   135                                const TDfc& aDataReceiveDfc );

   136 

   137     /**

   138     * Cancels the pending data receive request.

   139     * Data receive cancellation will cancel pending DataReceive DFC with

   140     * status KErrCancel. If nothing pending does nothing.

   141     * Preconditions: Channel is succesfully opened.

   142     * Postconditions: DataReceive is cancelled.

   143     * Called automatically in destructor.

   144     * Called in kernel thread context.

   145     * Called with no fastmutex held.

   146     * Called with interrupts enabled.

   147     * Called without kernel lock held.

   148     * @return None

   149     */

   150     IMPORT_C void DataReceiveCancel();

   151 

   152 

   153     /**

   154     * Sends a data message and deallocates the block given as parameter.

   155     * Preconditions: Channel is succesfully opened.

   156     *                Descriptor was allocated with AllocateDataMsgBlock.

   157     * Postconditions: Data message block is deallocated.

   158     * Called in kernel thread context.

   159     * Called with no fastmutex held.

   160     * Called with interrupts enabled.

   161     * Called without kernel lock held.

   162     * @param TDes8& aMsg, reference to message to be send.

   163     * @return TInt, an error code

   164     *               KErrNone, send succesfully

   165     *               KErrBadDescriptor, descriptor length too small.

   166     *               KErrUnderflow, ISI message length either bigger than descriptor

   167     *                              length or bigger than maximum ISI message length

   168     *                              or smaller than minimum ISI message length.

   169     *               KErrOverFlow, send queue overflow, client must resend.

   170     *               KErrNotReady, modem sw down, send failed, start listen state change, when ok, possible to resend.

   171     */

   172     IMPORT_C TInt DataSend( TDes8& aMsg );

   173 

   174 

   175     /**

   176     * Deallocates the message block retrieved with Receive.

   177     * NOTE! After deallocation set pointer to NULL.

   178     * Preconditions: Channel is succesfully opened.

   179     *                          Message was received with Receive.

   180     * Postconditions: Message block is deallocated.

   181     * Called in kernel thread context.

   182     * Called with no fastmutex held.

   183     * Called with interrupts enabled.

   184     * Called without kernel lock held.

   185     * @param aMsgBlock, reference to block to deallocate.

   186     * @return None

   187     */

   188     IMPORT_C void DeAllocateMsgBlock( TDes8& aMsgBlock );

   189 

   190     /**

   191     * Deallocates the data message block retrieved with DataReceive.

   192     * NOTE! After deallocation set pointer to NULL.

   193     * Preconditions: Channel is succesfully opened.

   194     *                          Data message was received with DataReceive.

   195     * Postconditions: Data message block is deallocated.

   196     * Called in kernel thread context.

   197     * Called with no fastmutex held.

   198     * Called with interrupts enabled.

   199     * Called without kernel lock held.

   200     * @param aMsgBlock, reference to data block to deallocate.

   201     * @return None

   202     */

   203     IMPORT_C void DeAllocateDataMsgBlock( TDes8& aMsgBlock );

   204 

   205     /**

   206     * Notifies flow control status change. When flowcontrol status changes

   207     * DFC will be queued and  status value updated to parameter.

   208     * Preconditions: Channel is succesfully opened.

   209     * Postconditions: Flowcontrol status notification is pending.

   210     * Kern::Fault will be raised if same request is set when it is already pending.

   211     * Called in kernel thread context.

   212     * Called with no fastmutex held.

   213     * Called with interrupts enabled.

   214     * Called without kernel lock held.

   215     * @param aNotifyFlowDfc, DFC function for flow status changes.

   216     * @param aDfcStatus, EIscFlowControlOn when datasend not allowed,

   217     *                    EIscFlowControlOff when datasend allowed,

   218     *                    EIscTransmissionEnd when datasend connection is removed

   219     *                    KErrCancel, when cancelled

   220     * @return None

   221     */

   222     IMPORT_C void NotifyFlowChange( TDfc& aNotifyFlowDfc,

   223                                     TInt& aDfcStatus );

   224 

   225     /** 

   226     * Cancels connection status change request.

   227     * Does nothing if request is not pending.

   228      * Preconditions: Channel is succesfully opened.

   229     * Postconditions: Flowcontrol status notification is cancelled.

   230     * Called automatically in destructor.

   231     * Called in kernel thread context.

   232     * Called with no fastmutex held.

   233     * Called with interrupts enabled.

   234     * Called without kernel lock held.

   235     * @return None

   236     */

   237     IMPORT_C void NotifyFlowChangeCancel();

   238 

   239     /**

   240     * Notifies connection status change. When connection status changes

   241     * DFC will be queued and connection status value updated to parameter.

   242     * Preconditions: Channel is succesfully opened.

   243     * Postconditions: Connection status notification is pending.

   244     * Kern::Fault will be raised if same request is set when it is already pending.

   245     * Called in kernel thread context.

   246     * Called with no fastmutex held.

   247     * Called with interrupts enabled.

   248     * Called without kernel lock held.

   249     * @param aNotifyStateDfc, DFC function for connection status changes.

   250     * @param aDfcStatus, EIscConnectionOk, EIscConnectionNotOk or KErrCancel

   251     * @return None

   252     */

   253     IMPORT_C void NotifyStateChange( TDfc& aNotifyStateDfc,

   254                                      TInt& aDfcStatus );

   255 

   256     /**

   257     * Cancels pending connection status notification with KErrCancel.

   258     * Does nothing if request not pending.

   259     * Preconditions: Channel is succesfully opened.

   260     * Postconditions: Connection status notification is cancelled.

   261     * Called automatically in destructor.

   262     * Called in kernel thread context.

   263     * Called with no fastmutex held.

   264     * Called with interrupts enabled.

   265     * Called without kernel lock held.

   266     * @return None 

   267     */

   268     IMPORT_C void NotifyStateChangeCancel() const;

   269 

   270     /**

   271     * Opens a clients channel. 

   272     * NOTE! If opened with resource client must give appropriate resource

   273     * as aResource.

   274     * Preconditions: Channel is closed.

   275     * Postconditions: Open is pending.

   276     * Kern::Fault will be raised if same request is set when it is already pending.

   277     * Called in kernel thread context.

   278     * Called with no fastmutex held.

   279     * Called with interrupts enabled.

   280     * Called without kernel lock held.

   281     * @param aChannelNumber, clients dedicated channel number.

   282     * @param aDfcStatus, updated when DFC queued. 

   283     *                KErrNone, is succesfully

   284     *                KErrAlreadyExist, channel already open

   285     *                KErrNotSupported, open with resource failed.

   286     * @param aOpenDfc, ref. to DFC  to be queued when channel is opened.

   287     * @param aResource, 32-bit resourceid default value (PN_NO_ROUTING (0xff)).

   288     * @return None

   289     */

   290     IMPORT_C void Open( const TUint16 aChannelNumber, TInt& aDfcStatus,

   291                         TDfc& aOpenDfc, const TUint32 aResource = 0x000000ff );

   292 

   293     /**

   294     * Cancels the pending open DFC request with KErrCancel.

   295     * If the open is not pending anymore does nothing.

   296     * Called automatically in destructor.

   297     * Called in kernel thread context.

   298     * Called with no fastmutex held.

   299     * Called with interrupts enabled.

   300     * Called without kernel lock held.

   301     * @return None

   302     */

   303     IMPORT_C void OpenCancel();

   304 

   305     /**

   306     * Receive message. DFC function given as param

   307     * shall be queued to run when message is received.

   308     * NOTE! After Receive DFC completion, client must deallocate block with

   309     * DeAllocateBlock and set the pointer to NULL.

   310     * Preconditions: Channel is succesfully opened.

   311     *                Parameter aMsgBlock must be NULL.

   312     * Postconditions: Receive is pending.

   313     * Kern::Fault will be raised if API can't allocate receive buffer.

   314     * Kern::Fault will be raised if same request is set when it is already pending.

   315     * Called in kernel thread context.

   316     * Called with no fastmutex held.

   317     * Called with interrupts enabled.

   318     * Called without kernel lock held.

   319     * @param aMsgBlock, block where receive message is stored.

   320     * @param aStatus, updated when DFC is queued. 

   321     *                 KErrNone, succefull

   322     *                 KErrCancel, receive was cancelled client no need to deallocate block get from receive.

   323     * @param aReceiveDfc, clients DFC function for receiving message. 

   324     * @return None

   325     */

   326     IMPORT_C void Receive( TDes8*& aMsgBlock, TInt& aStatus,

   327                            const TDfc& aReceiveDfc );

   328 

   329     /**

   330     * Cancels the pending receive DFC request with KErrCancel.

   331     * If the receive is not pending anymore does nothing.

   332     * Preconditions: Channel is succesfully opened.

   333     * Called automatically in destructor.

   334     * Called in kernel thread context.

   335     * Called with no fastmutex held.

   336     * Called with interrupts enabled.

   337     * Called without kernel lock held.

   338     * @return None

   339     */

   340     IMPORT_C void ReceiveCancel();

   341 

   342     /**

   343     * Sends a message and deallocates the block given as parameter.

   344     * Preconditions: Channel is succesfully opened.

   345     *                Descriptor was allocated with AllocateMsgBlock.

   346     * Postconditions: Message block is deallocated.

   347     * Called in kernel thread context.

   348     * Called with no fastmutex held.

   349     * Called with interrupts enabled.

   350     * Called without kernel lock held.

   351     * @param TDes8& aMsg, reference to message to be send.

   352     * @return TInt, an error code

   353     *               KErrNone, send succesfully

   354     *               KErrBadDescriptor, descriptor length too small.

   355     *               KErrUnderflow, ISI message length either bigger than descriptor

   356     *                              length or bigger than maximum ISI message length

   357     *                              or smaller than minimum ISI message length.

   358     *               KErrOverFlow, send queue overflow, client must resend.

   359     *               KErrNotReady, modem sw down, send failed, start listen state change, when ok, possible to resend.

   360     */

   361     IMPORT_C TInt Send( TDes8& aMsg );

   362 

   363     /**

   364     * Sends an event to CMT. NOTE! Only servers in ISA-sense can do this.

   365     * Preconditions: Channel is succesfully opened with resource.

   366     *                Block was allocated with AllocateMsgBlock.

   367     * Postconditions: Indication was send.

   368     *                 Block was deallocated.

   369     * Called in kernel thread context.

   370     * Called with no fastmutex held.

   371     * Called with interrupts enabled.

   372     * Called without kernel lock held.

   373     * @param TDes8& aMsg, reference to indication to be send.

   374     * @return TInt, an error code.

   375     *               KErrNone, send succesfully

   376     *               KErrBadDescriptor, descriptor length too small.

   377     *               KErrUnderflow, ISI message length either bigger than descriptor

   378     *                              length or bigger than maximum ISI message length

   379     *                              or smaller than minimum ISI message length.

   380     *               KErrOverFlow, send queue overflow, client must resend.

   381     *               KErrNotReady, modem sw down, send failed, start listen state change, when ok, possible to resend.

   382     */

   383     IMPORT_C TInt SendIndication( TDes8& aMsg );

   384 

   385     /**

   386     * Subscribe indications. Indications are received with

   387     * Receive.

   388     * NOTE! Don't dellocate the descriptor for indications.

   389     * 8-bit subscribing list item. Must be div. by two.

   390     *                               byte1:[8bit resourceid]

   391     *                               byte2:[8bit indicationid]

   392     * 32-bit subscribing list item. Must be div. by five.

   393     *                               byte1:[32-24 bits of resourceid]

   394     *                               byte2:[24-16 bits of resourceid]

   395     *                               byte3:[16-8 bits of resourceid]

   396     *                               byte4:[8-0 bits of resourceid]

   397     *                               byte5:[8bit indicationid]

   398     * Preconditions: Channel is succesfully opened.

   399     * Postconditions: Channel is add as indication(s) subscriber.

   400     * Called in kernel thread context.

   401     * Called with no fastmutex held.

   402     * Called with interrupts enabled.

   403     * Called without kernel lock held.

   404     * @param aIndications, indication subscription list.

   405     * @param aThirtyTwoBit, EFalse by default, ETrue when 32-bit subscribing used. 

   406     * @return TInt, an error code.

   407     *               KErrNone, subscribe succesfully

   408     *               KErrBadDescriptor, descriptor length too small or not according to subscribing list items.

   409     *               KErrUnderflow, subscribing list item too long.

   410     *               KErrOverFlow, send queue overflow, client must resend.

   411     *               KErrNotReady, modem sw down, send failed, start listen state change, when ok, possible to resend.

   412     */

   413     IMPORT_C TInt SubscribeIndications( const TDesC8& aIndications,

   414                                         const TBool aThirtyTwoBit = EFalse );

   415 

   416     private:

   417 

   418     /**

   419      * Private constructor.

   420      * One reason class size BC.

   421      */

   422     DIsaKernelAPI();

   423 

   424     private:

   425 

   426     // Owned

   427     // Kernel channel dedicated for this.

   428     DISAKernelChannel*      iKernelChannel;

   429 

   430     };

   431 

   432 #endif // ISAKERNELAPI_H

   433 

   434 // End of File.

   435