/*=================================================================================

FILE: AEEPort.h

SERVICES:  
   IPort interface.

GENERAL DESCRIPTION:
   Bidirectional IO interface derived from ISource.
           

         Copyright © 1999-2002 QUALCOMM Incorporated.
                   All Rights Reserved.
                 QUALCOMM Proprietary/GTDR
=================================================================================*/
#ifndef _AEEPORT_H_
#define _AEEPORT_H_

#include "AEE.h"
#include "AEESource.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Return Codes for Read */
#define AEEPORT_CLOSED    ISOURCE_END
#define AEEPORT_ERROR     ISOURCE_ERROR
#define AEEPORT_WAIT      ISOURCE_WAIT


/* INTERFACE - IPort
|| 
|| IPort
||    ISource
||    IQueryInterface
||    IBase
|| 
*/

// Use to inherit from an IPort
#define INHERIT_IPort(iname)\
   INHERIT_ISource(iname); \
   int   (*GetLastError)(iname * po); \
   int32 (*Write)(iname *pme, const char *pcBuf, int32 cbBuf); \
   void  (*Writeable)(iname *pme, AEECallback *pcb); \
   int   (*IOCtl)(iname *po, int nOption, uint32 dwVal); \
   int   (*Close)(iname * po); \
   int   (*Open)(iname * po, const char * szPort)

typedef struct _IPort IPort;
AEEINTERFACE(IPort){
   INHERIT_IPort(IPort);
};

#define IPORT_AddRef(p)                   AEEGETPVTBL((p),IPort)->AddRef((p))
#define IPORT_Release(p)                  AEEGETPVTBL((p),IPort)->Release((p))
#define IPORT_QueryInterface(p,i,ppo)     AEEGETPVTBL((p),IPort)->QueryInterface((p),(i),(ppo))
#define IPORT_Read(p,pc,cb)               AEEGETPVTBL((p),IPort)->Read((p),(pc),(cb))
#define IPORT_Readable(p,pcb)             AEEGETPVTBL((p),IPort)->Readable((p),(pcb))
#define IPORT_GetLastError(p)             AEEGETPVTBL((p),IPort)->GetLastError((p))
#define IPORT_Write(p,pc,cb)              AEEGETPVTBL((p),IPort)->Write((p),(pc),(cb))
#define IPORT_Writeable(p,pcb)            AEEGETPVTBL((p),IPort)->Writeable((p),(pcb))
#define IPORT_IOCtl(p,opt,v)              AEEGETPVTBL((p),IPort)->IOCtl((p),(opt),(v))
#define IPORT_Close(p)                    AEEGETPVTBL((p),IPort)->Close((p))
#define IPORT_Open(p,pname)               AEEGETPVTBL((p),IPort)->Open((p),(pname))




#define IPORT_ReadableEx(p,pcb,pfn,pv)    CALLBACK_Init((pcb),(pfn),(pv)); \
                                          IPORT_Readable((p), (pcb))

#ifdef __cplusplus
}
#endif

/*=====================================================================
  DATA STRUCTURE DOCUMENTATION
======================================================================= 
=====================================================================
  MACROS DOCUMENTATION
======================================================================= 
=======================================================================
  INTERFACES DOCUMENTATION
======================================================================= 

IPort Interface

Description:
   Generic interface for bidirectional data stream providing 
   Read/Readable, Write/Writeable, GetLastError and IOCtl interfaces.

   As IPort is a generic interface, it must be created using class id 
   specific to its usage.

   For example:
   For Serial IO usage, use AEECLSID_SERIAL.
======================================================================= 

IPORT_AddRef()

Description:
    This function is inherited from IBASE_AddRef(). 

Version:
   Introduced BREW Client 3.0
  
See Also:
    IPORT_Release()

=======================================================================

IPORT_Release()

Description:
    This function is inherited from IBASE_Release(). 

Version:
   Introduced BREW Client 3.0

See Also:
    IPORT_AddRef()

=======================================================================

IPORT_QueryInterface()

Description:
    This function is inherited from IQI_QueryInterface().
    It can be used to
     -    Get a pointer to an available interface based on the input class ID
     -    Query an extended version of the IPort-derived class

Prototype:
    int IPORT_QueryInterface
    (
    IPort* pIPort, 
    AEECLSID clsReq, 
    void ** ppo
    )

Parameters:
    pIPort:  [in]:  Pointer to IPort Interface.
    clsReq:  [in]:  Class ID of the interface to query.
    ppo:  [out]:  Pointer to the interface.

Return Value:
    SUCCESS: on success, 
    Otherwise: an error code.

Comments:
    If ppo is back a NULL pointer, the queried interface is not available.

Side Effects:
    If an interface is retrieved, then this function increments its reference count.

Version:
   Introduced BREW Client 3.0

See Also:
    None

======================================================================= 

IPORT_Read()

Description: 
   Copy bytes from the source stream to the specified buffer.  All copied 
   bytes are "consumed" (i.e. the "read pointer" is advanced).

Prototype:
   int32 IPORT_Read
   (
      IPort *po, 
      char *pc, 
      int32 cb
   )

Parameters:
   po: Pointer IPort object
   pc: pointer to buffer to receive bytes read
   cb: size of pc

Return Value: 
   If the return value is greater than zero, the return 
   value indicates the number of bytes successfully read.
    
   Otherwise, the return value will be one of:
 ~
   AEEPORT_CLOSED   : peer shut down connection gracefully (no more data)~
   AEEPORT_ERROR    : error was encountered (no more data)~
   AEEPORT_WAIT     : no data available at the moment. call Readable() to wait~
*

Comments:  
   Note that the AEEPORT_WAIT return value is used instead of
   an error return value and an EWOULDBLOCK error code.

Side Effects:
   None

Version:
   Introduced BREW Client 3.0

See Also:
   IPORT_Readable()

======================================================================= 

IPORT_Readable()

Description: 
   Schedule a function to be called when IPORT_Read() would
   return something other than AEEPORT_WAIT.


Prototype:
   void IPORT_Readable
   (
      IPort *po, 
      AEECallback *pcb
   )

Parameters:
   po :  Pointer IPort object   
   pcb:  Pointer to a pre-initialized AEECallback struct which 
                      contains a function to call when the IPort may be 
                      read with IPORT_Read().

Return Value: 
   None

Comments:
   The AEECallback struct pointed to by the 'pcb' parameter must be 
   initialized with the CALLBACK_Init() macro before calling this funciton.

Side Effects:
   None

Version:
   Introduced BREW Client 3.0

See Also:
   IPORT_Read()

======================================================================= 

IPORT_GetLastError()

Description:
  This function returns the last error that occurred with the IPort. The
  value returned depends on the most recently called function. The documentation
  for each function, of the interface that implemented IPort, describes what 
  GetLastError() can return when called right after that function. 

Prototype:
  int IPORT_GetLastError
  (
   IPort * po
  )

Parameters:
  po: Pointer to IPort object

Return Value:
   The most recently occurred error.  This could be any BREW error code.

   The most common ones are listed below.
~

   AEEPORT_ENOTOPEN  - Port is not open~
   EBADSTATE         - The port is in an incompatible state~
*
   
Comments:  
   None

Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   IPORT_Read()
   IPORT_Write()

===========================================================================

IPORT_Write()

Description: 
   Copy bytes from the specified buffer to the source stream.  All copied 
   bytes are "consumed" (i.e. the "write pointer" is advanced).


Prototype:
   int32 IPORT_Write
   (
      IPort *po, 
      const char *pcBuf, 
      int32 cbBuf
   )

Parameters:
   po   :  pointer to the IPort object
   pcBuf:  pointer to buffer from which bytes are taken to write to the port
   cbBuf:  size of data in pcBuf

Return Value: 
   If the return value is greater than zero, the return 
   value indicates the number of bytes successfully written.
    
   Otherwise, the return value will be one of:
~   
   AEEPORT_CLOSED   : peer shut down connection gracefully (no more data)~
   AEEPORT_ERROR : error was encountered (no more data)~
   AEEPORT_WAIT  : no data available at the moment; call Writeable() to wait~
*


Comments:  
   Note that the AEEPORT_WAIT return value is used instead of
   an error return value and an EWOULDBLOCK error code.

Side Effects:
   None

Version:
   Introduced BREW Client 3.0

See Also:
   IPORT_Writeable()

======================================================================= 

IPORT_Writeable()

Description: 
   Schedule a function to be called when IPORT_Write() would
   return something other than AEEPORT_WAIT.


Prototype:
   void IPORT_Writeable
   (
      IPort *po, 
      AEECallback *pcb
   )

Parameters:
   po: Pointer IPort object
   pcb:  Pointer to a pre-initialized AEECallback struct which 
         contains a function to call when the IPort may be 
         writeable with IPORT_Write().

Return Value: 
   None

Comments:
   The AEECallback struct pointed to by the 'pcb' parameter must be 
   initialized with the CALLBACK_Init() macro before calling this funciton.

Side Effects:
   None

Version:
   Introduced BREW Client 3.0

See Also:
   IPORT_Write()

======================================================================= 

IPORT_IOCtl()

Description:
   This function allows some control over the behaviour of an IPort, 
   e.g. setting/getting configuration.

   Its form is analogous to SYSV's ioctl, with encoded arguments that
   should be specified with the *_IOCTL_* macros listed here.  It's 
   intended use is for special, out-of-object-signature behaviour.  For
   that reason, it is super-generic.

Prototype:
   int IPORT_IOCtl
   (
      IPort * po, 
      int nOption, 
      uint32 dwVal
   )

Parameters:
   po:         Pointer to the IPort object
   nOption:    the option id
   dwVal:      option value : this value depends on the option id. If could be 
               a 32 bit value or a pointer to a structure that is specific to 
               the option id

Return Value:
  SUCCESS -  the option id is known and the specified operation succeeds

  EUNSUPPORTED - the option id was unrecognized

  other failure return codes, depending on the option id specified
   
Comments:

  Currently supported option ids are specified by each interface that 
  implements them

  
Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   None
======================================================================= 

IPORT_Open()

Description:
   This function allows opens the given port. This call becomes
   asynchronous if the AEEPORT_WAIT error code is returned. The app
   on receving this error code should call Writeable to be notified when 
   calling IPORT_Open() would return a different result. The app can also 
   choose to wait on a timer, which is more like polling.

   Call IPORT_Close() to stop a pending IPORT_Open()

Prototype:
   int IPORT_Open
   (
      IPort *po, 
      const char * szPort
   )

Parameters:
   po:      Pointer to the IPort object
   szPort:  Name of the port to be opened
                 
Return Value:
  SUCCESS         - Successfully opened the port

  AEEPORT_WAIT    - Open in progress; Call Open() again for status

  AEEPORT_EINUSE  - Port is currently open by some other entity

  ENOSUCH         - The asked port name is not supported

  ENOMEMORY       - Out of memory

  EFAILED         - General failure code

Comments:
  IPort is an abstract interface. Hence, the supported names must be looked up
  in each implementation's specific header file (such as AEESio.h for Serial Ports)
  
  
Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   None

======================================================================= 

IPORT_Close()

Description:
   This function closes an opened port or stops a open in progress.

Prototype:
   int IPORT_Close
   (
      IPort *po
   )

Parameters:
   po: Pointer to the IPort object
                 
Return Value:
  SUCCESS  - Successfully closed the port

  AEEPORT_ENOTOPEN - Port is not in open state

  EFAILED  - Generic failure code
   
Comments:
  
Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   None

=============================================================================*/

#endif  //_AEEPORT_H_

