capimms.h

彩信MMS的全部代码

/*
 * Copyright (C) Obigo AB, 2002-2005.
 * All rights reserved.
 *
 * This software is covered by the license agreement between
 * the end user and Obigo AB, and may be 
 * used and copied only in accordance with the terms of the 
 * said agreement.
 *
 * Obigo AB assumes no responsibility or 
 * liability for any errors or inaccuracies in this software, 
 * or any consequential, incidental or indirect damage arising
 * out of the use of the software.
 *
 */

/******************************************************************************
 * File:            $Workfile:   capimms.h  $
 * Revision:        $Revision: \main\150 $
 *****************************************************************************/

/*! \file capimms.h
 *  \brief Exported connector functions towards the MMS Client.
 *
 * Exported connector functions, i.e. from Target Device Application to the MMS 
 * client. For every connector function, the following data are listed:
 * - A brief one line description of the function
 * - A longer description of the function
 * - The type of the function. It can be either:
 *     -# Request Connector: The MMS Application requests services from the 
 *        MMS client via this connector. The result will be returned in an 
 *        Answer Adapter.
 *     -# Answer Connector: The MMS client has requested a service, via a 
 *        Service Adapter, from the MMS Application. The result to this 
 *        request is returned via the described connector.
 * - The name of the corresponding adapter function
 * - The parameters for the function
 */

#ifndef _CAPIMMS_H
#define _CAPIMMS_H

#ifndef _MMSCONF_H  /* Check so mmsconf.h is included before this file */
#error You must #include mmsconf.h before this file.
#error The file mmsconf.h contains configuration data for all other MMS files.
#error Please change the .c file that stopped from compiling because you came 
#error here so that it includes mmsconf.h before this file.
#endif /* _MMSCONF_H */

/*--- Definitions/Declarations ---*/

/*--- Types ---*/

/*--- Constants ---*/

/*--- Forwards ---*/

/*--- Externs ---*/

/*--- Macros ---*/

/*--- Prototypes ---*/

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_createMessageResponse
 *
 * This function creates an empty message in the draft folder.
 *
 * All operations (e.g. send, move, modify) on messages in the MMS client use 
 * a unique message ID. Before these operations can be performed, a message ID
 * and folder space must be created. This function performs both operations.
 *
 *****************************************************************************/
void MMSc_createMessage(void);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_createMessageDoneResponse
 *
 * This function indicates to the MMS client that the creation of a message is 
 * done. When creating a Multimedia Message, it can contain multiple parts. 
 * When this connector is called, no more parts will be added. 
 *
 * \param msgId A unique identity for a multimedia message.
 *****************************************************************************/
void MMSc_createMessageDone(MmsMsgId msgId);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_createMultiPartEntryResponse
 *
 * This function creates a separate multi-part entry that can be added later 
 * to a message. Normally a message is created with the following calls:
 *  - #MMSc_createMessage
 *  - #MMSc_setMessageHeader
 *  - #MMSc_setMessageBody
 *  - #MMSc_createMessageDone
 *
 * If the message is complex and consists of a hierarchy of multipart 
 * messages, the lower levels of multipart messages must first be created 
 * with this connector and can thereafter be inserted into the message 
 * structure.
 *
 * \param numOfEntries Number of entries for this multi-part.
 *****************************************************************************/
void MMSc_createMultiPartEntry(UINT32 numOfEntries);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_deleteFolderResponse
 *
 * All stored messages in a folder is deleted.
 *
 * \param folder The folder where all messages should be deleted. 
 * \param ignoreFilter Messages that should not be deleted. Consists of one or 
 *      more CmnMsgAttributes values joined in a bitwise OR.
 *****************************************************************************/
void MMSc_deleteFolder( MmsFolderType folder, UINT8 ignoreFilter);

/*!
 * Type: Request Connector
 *
 * Related Adapter: None.
 *
 * An ongoing delete folder operation is cancelled by this function. Only one 
 * delete folder operation can be executed at a time, so the last call to 
 * #MMSc_deleteFolder is cancelled. 
 *****************************************************************************/
void MMSc_deleteFolderCancel(void);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_deleteMessageResponse
 *
 * A previously stored message is deleted from the folder in which it is 
 * stored. Both body and header part of the message are deleted.
 *
 * \param msgId A unique identity for a multimedia message.
 *****************************************************************************/
void MMSc_deleteMessage(MmsMsgId msgId);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_deleteMessageIdListResponse
 *
 * A number of previously stored messages are deleted from the folder in which 
 * it is stored. Both body and header part of the messages are deleted.
 *
 * \param msgIds An array of identities for multimedia messages.
 * \param number The number of identies in the array.
 *****************************************************************************/
void MMSc_deleteMessageIdList( const MmsMsgId msgIds[], UINT32 number);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_deleteMessageIdListResponse
 *
 * Cancels an ongoing #MMSa_deleteMessageIdList operation.
 *****************************************************************************/
void MMSc_deleteMessageIdListCancel(void);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_deleteTemporaryFilesResponse
 *
 * This function deletes all temporary files.
 *
 * When larger messages and attachments are delivered to the MMS Application
 * they are stored as temporary files. Separate multipart entries are also 
 * stored as temporary files. The MMS Application should delete these files 
 * using the standard FILE API when the MMS Application no longer needs them. 
 * The MMS Application can also from time to time delete all previously created 
 * temporary files with this function.
 *
 *****************************************************************************/
void MMSc_deleteTemporaryFiles(void);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_forwardReqResponse
 *
 * This function sends a forward request to an MMS Proxy-Relay.
 *
 * When a notification is received, before the actual message has been 
 * fetched, the MMS Application can send a request to the MMS Proxy-Relay
 * to directly forward the message to another recipient.
 *
 * \param forward Information about the forward to be made. This data is copied 
 *      by the MMS Client if needed after the connector function returns.
 * \param notifId The identity of a notification.
 *****************************************************************************/
void MMSc_forwardReq(const MmsForward *forward, MmsMsgId notifId);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_getBodyPartResponse
 *
 * This function initiates a get operation of a part from a message body. A
 * chunk of the body part or a file reference is returned in the corresponding 
 * adapter function.
 *
 * \param msgId The message to get the body part from.
 * \param number The number of the requested body part
 *****************************************************************************/
void MMSc_getBodyPart( MmsMsgId msgId, UINT32 number);

#ifdef MMS_STANDARD_INTERFACE
/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_getConfigIntResponse
 *
 * Get the value of a configuration variable
 *
 * The value of a configuration variable of integer type is returned.
 * This function is only available if MMS_STANDARD_INTERFACE is defined.
 *
 * \param key The variable whose value are requested.
 *****************************************************************************/
void MMSc_getConfigInt(MmsConfigInt key);
#endif /* MMS_STANDARD_INTERFACE */

#ifdef MMS_STANDARD_INTERFACE
/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_getConfigStrResponse
 *
 * Get the value of a configuration variable
 *
 * The value of a configuration variable of string type is returned.
 * This function is only available if MMS_STANDARD_INTERFACE is defined.
 *
 * \param key The variable whose value are requested.
 *****************************************************************************/
void MMSc_getConfigStr(MmsConfigStr key);
#endif /* MMS_STANDARD_INTERFACE */

#ifdef MMS_EXTERNAL_DRM_ID_GENERATION
/*!
 * Type: Answer Connector.
 *
 * Related Adapter: #MMSa_getDrmId
 *                      
 * This function request a unique ID to assign to DRM protected bodyparts.
 *
 * This function is only available if #MMS_EXTERNAL_DRM_ID_GENERATION is 
 * defined.
 * 
 * \param msgId The message id.
 * \param drmId The id returned by the application layers DRM utility.
 * \param contFinish Value passed from call to #MMSa_getDrmId.
 *
 *****************************************************************************/
void MMSc_getDrmIdResponse( MmsMsgId msgId, UINT32 drmId, UINT32 contFinish);
#endif  /* MMS_EXTERNAL_DRM_ID_GENERATION */

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_getMessageResponse
 *
 * The MMS Application requests a message header, a notification or a body
 * information list.
 *
 * \param msgId A unique identity for a multimedia message.
 * \param msgType The type of message requested.
 *****************************************************************************/
void MMSc_getMessage(MmsMsgId msgId, MmsMsgType msgType);

/*!
 * Type: Request Connector
 *
 * Related Adapter: #MMSa_getMessageDateResponse
 *
 * Get the date for a message.
 *
 * \param msgId A unique identity for a multimedia message.
 *****************************************************************************/
void MMSc_getMessageDate( MmsMsgId msgId);