/*

* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:   Interface MCatalogsClientServer declaration 

*

*/

#ifndef M_CATALOGS_CLIENT_SERVER_H

#define M_CATALOGS_CLIENT_SERVER_H

#include <f32file.h>

class TRequestStatus;

class TDesC8;

class TDes8;

class HBufC8;

/**

 *  An interface including message sending methods

 *

 *  This interface is used on the client side

 *  to send messages to the server side objects 

 *

 *  @lib ?library

 *  @since S60 ?S60_version *** for example, S60 v3.0

 */

class MCatalogsClientServer

    {

public:

    /**

     * Sends a message to a server side object

     * and waits synchronously for the reply

     *

     * @since S60 ?S60_version

     * @param aFunction the opcode specifying the requested service

     * @param aInput input data to be sent

     * @param aOutput a descriptor where the output data can be written

     *                  The maximum length of the output data must be known and

     *                  the descriptor allocated accordingly

     * @param aHandle a handle that is used to specify the receiving

     *                  object on the server side

     * @return KErrNone if successful, otherwise an error code

     */

    virtual TInt SendSync( TInt aFunction,

                           const TDesC8& aInput,

                           TDes8& aOutput,

                           TInt aHandle ) = 0;

     /**

     * Sends a message to a server side object

     * and waits synchronously for the reply

     *

     * @since S60 ?S60_version

     * @param aFunction the opcode specifying the requested service

     * @param aInput input data to be sent

     * @param aOutput a descriptor where the output data can be written

     *                  The maximum length of the output data must be known and

     *                  the descriptor allocated accordingly

     * @param aHandle a handle that is used to specify the receiving

     *                  object on the server side

     * @return KErrNone if successful, otherwise an error code

     */

    virtual TInt SendSync( TInt aFunction,

                           const TDesC16& aInput,

                           TDes16& aOutput,

                           TInt aHandle ) = 0;

     /**

     * Sends a message to a server side object

     * and waits synchronously for the reply

     *

     * @since S60 ?S60_version

     * @param aFunction the opcode specifying the requested service

     * @param aInput input data to be sent

     * @param aOutputInt a integer where the output data can be written

     * @param aHandle a handle that is used to specify the receiving

     *                  object on the server side

     * @return KErrNone if successful, otherwise an error code

     */

    virtual TInt SendSync( TInt aFunction,

                           const TDesC16& aInput,

                           TInt& aOutputInt,

                           TInt aHandle ) = 0;    

     /**

     * Sends a message to a server side object

     * and waits synchronously for the reply

     *

     * @since S60 ?S60_version

     * @param aFunction the opcode specifying the requested service

     * @param aInput input data to be sent

     * @param aOutputInt a integer where the output data can be written

     * @param aHandle a handle that is used to specify the receiving

     *                  object on the server side

     * @return KErrNone if successful, otherwise an error code

     */

    virtual TInt SendSync( TInt aFunction,

                           const TDesC8& aInput,

                           TInt& aOutputInt,

                           TInt aHandle ) = 0;  

    /**

     * Sends a message to a server side object

     * and waits synchronously for the reply. The maximum length

     * of the output data does not have to be known beforehand. The 

     * implementing class allocates an output buffer of adequate length.

     * NOTICE: If user sends a message from the server-side with some

     *         other outcome than KErrNone, it passes through (when it is

     *         not KCatalogsErrorTooSmallDescriptor) and the

     *         output message has to be deleted after usage.

     *         If outcome is KCatalogsErrorTooSmallDescriptor, a null-pointer

     *         is received.

     * NOTICE: aOutput should be initially a NULL-pointer

     *

     * @since S60 ?S60_version

     * @param aFunction the opcode specifying the requested service

     * @param aInput input data to be sent

     * @param aOutput a reference to a pointer that points to a descriptor

     *                  that includes the output data when after the reply

     *                  is received from the server

     * @param aHandle a handle that is used to specify the receiving

     *                  object on the server side

     * @param aLength estimated maximum length of the output data. This length

     *              does not have to be known for sure when sending a message

     * @return KErrNone if successful, otherwise an error code

     */

    virtual TInt SendSyncAlloc( TInt aFunction,

                                const TDesC8& aInput,

                                HBufC8*& aOutput,

                                TInt aHandle,

                                TInt aLength ) = 0;

    /**

     * Sends a message to a server side object

     * and waits synchronously for the reply. The maximum length

     * of the output data does not have to be known beforehand. The 

     * implementing class allocates an output buffer of adequate length.

     * NOTICE: If user sends a message from the server-side with some

     *         other outcome than KErrNone, it passes through (when it is

     *         not KCatalogsErrorTooSmallDescriptor) and the

     *         output message has to be deleted after usage.

     *         If outcome is KCatalogsErrorTooSmallDescriptor, a null-pointer

     *         is received.

     * NOTICE: aOutput should be initially a NULL-pointer

     *

     * @since S60 ?S60_version

     * @param aFunction the opcode specifying the requested service

     * @param aInput input data to be sent

     * @param aOutput a reference to a pointer that points to a descriptor

     *                  that includes the output data when after the reply

     *                  is received from the server

     * @param aHandle a handle that is used to specify the receiving

     *                  object on the server side

     * @param aLength estimated maximum length of the output data. This length

     *              does not have to be known for sure when sending a message

     * @return KErrNone if successful, otherwise an error code

     */

    virtual TInt SendSyncAlloc( TInt aFunction,

                                const TDesC16& aInput,

                                HBufC16*& aOutput,

                                TInt aHandle,

                                TInt aLength ) = 0;

    /**

     * Sends a message to a server side object

     * and waits asynchronously for the reply. 

     *

     * @since S60 ?S60_version

     * @param aFunction the opcode specifying the requested service

     * @param aInput input data to be sent

     * @param aOutput a descriptor where the output data can be written.

     *                  The maximum length of the output data must be known and

     *                  the descriptor allocated accordingly

     * @param aHandle a handle that is used to specify the receiving

     *                  object on the server side

     * @param aStatus a request status which indicates the completion 

     *                  status of the asynchronous request.

     */

    virtual void SendAsync( TInt aFunction,

                            const TDesC8& aInput,

                            TDes8& aOutput,

                            TInt aHandle,

                            TRequestStatus& aStatus ) = 0;

    /**

     * Sends a file open message to a server side object. The server side object

     * should return an open RFile handle

     *

     * @since S60 ?S60_version

     * @param aFunction the opcode specifying the requested service

     * @param aInput input data to be sent

     * @param aOutput Open RFile

     *                

     * @param aHandle a handle that is used to specify the receiving

     *                  object on the server side

     * @param aStatus a request status which indicates the completion 

     *                  status of the asynchronous request.

     */

    virtual RFile SendSyncFileOpenL( TInt aFunction,

                                     const TDesC8& aInput,

                                     TInt aHandle ) = 0;    

    /**

     * Sends a message to a server side object

     * and waits asynchronously for the reply. The maximum length

     * of the output data does not have to be known beforehand. The 

     * implementing class allocates an output buffer of adequate length.

     * NOTICE: If user sends a message from the server-side with some

     *         other outcome than KErrNone, it passes through (when it is

     *         not KCatalogsErrorTooSmallDescriptor) and the

     *         output message has to be deleted after usage.

     *         If outcome is KCatalogsErrorTooSmallDescriptor, a null-pointer

     *         is received.

     * NOTICE: aOutput should be initially a NULL-pointer

     *

     * @since S60 ?S60_version

     * @param aFunction the opcode specifying the requested service

     * @param aInput input data to be sent

     * @param aOutput a reference to a pointer that points to a descriptor

     *                  that includes the output data when after the reply

     *                  is received from the server

     * @param aHandle a handle that is used to specify the receiving

     *                  object on the server side

     * @param aStatus a request status which indicates the completion 

     *                  status of the asynchronous request.

     * @param aLength estimated maximum length of the output data. This length

     *              does not have to be known for sure when sending a message

     */

    virtual void SendAsyncAlloc( TInt aFunction,

                                  const TDesC8& aInput,

                                  HBufC8*& aOutput,

                                  TInt aHandle,

                                  TRequestStatus& aStatus,

                                  TInt aLength ) = 0;

    /**

     * Informs ClientServer that sender has gone down and no messages

     * related to that specific sender should be completed anymore by

     * ClientServer. ClientServer still expects that the messages that

     * were sent from the sender are completed by the receiver on the

     * server side.

     *

     * @notice aStatus has to be the same TRequestStatus that was given

     *         when sending the message. Comparation is done simply by

     *         comparing the addresses of TRequestStatus given now and

     *         TRequestStatuses given during message sends.

     *

     * @since S60 ?S60_version

     * @param aStatus TRequestStatus that identifies the sender whose

     *                messages should not be completed anymore.

     *

     */

    virtual void AsyncMessageSenderDown( TRequestStatus& aStatus ) = 0;

    };

#endif // M_CATALOGS_CLIENT_SERVER_H