obex.h

SyncML手册及其编程

**    appended no additional data to the header list.  Returns OBX_RC_STREAM_EOF if transaction is
**    complete.
**    Returns
**       OBX_RC_OK         -  Success but more data is expected.  User should continue to call
**                            ObxStreamRecv() to accept data.
**       OBX_RC_STREAM_EOF -  Success, final bit from peer, no more data expected on stream.
**
** ObxStreamFlush()
**    Causes all queued headers, entered with the ObxStreamSend() call, to be sent to the peer.
**
** ObxStreamClose()
**    Closes the stream (flushes all remaining buffers, if writing).
**
** ObxStreamFree()
**    Returns storage associated with the passed stream object.
**
*/
#ifndef RAW_API_ONLY
OBEX_EXPORT ObxStream      *ObxStreamNew();

OBEX_EXPORT ObxRc          ObxStreamingSend( ObxHandle *handle, ObxObject *request, ObxStream *stream );
OBEX_EXPORT ObxRc          ObxStreamingRecv( ObxHandle *handle, ObxObject *request, ObxStream *stream );

OBEX_EXPORT ObxRc          ObxStreamSend( ObxStream *stream, unsigned char *data, int len );
OBEX_EXPORT ObxRc          ObxStreamRecv( ObxStream *stream, ObxList *headerList );

OBEX_EXPORT ObxRc          ObxStreamFlush( ObxStream *stream );
OBEX_EXPORT ObxRc          ObxStreamClose( ObxStream *stream );

OBEX_EXPORT ObxRc          ObxStreamFree( ObxStream *stream );
#endif


/*
**************************************************************************
**
** Methods to create and destroy an object
**
** ObxObjectNew():
**    Create a new object.  The passed command type is used to initialize it.
**    The caller will then add headers prior to flowing the request to the peer.
**
** ObxObjectNewResponse()
**    Forms an ObxObject for the given request object.  The response code
**    is indicated by the passed ObxCommand.
**    The caller is free to add appropriate headers prior to flowing the response
**    to the peer.
**
** ObxObjectSetConnectMeta()
** ObxObjectSetSetPathMeta()
**    Set's meta data specific to the OBEX_CMD_CONNECT and OBEX_CMD_SETPATH
**    objects.
**
** ObxObjectFree():
**    Return all memory associated with the passed object.
**
** ObxObjectReset()
**    Resets the internals of an ObxObject so it can be reused.  The command type
**    is used to determine if meta data objects need to be freed.
**
** ObxObjectAddHeader()
**    Add a ObxHeader to an ObxObject.
**
** ObxObjectGetHeaderList()
**    Retrieve the list of ObxHeaders from the object.
**
** ObxObjectGetCommand()
**    What command is associated with this object?  Returns the command
**    or -1 on error.
**
**************************************************************************
*/
OBEX_EXPORT ObxObject*     ObxObjectNew( ObxHandle *handle, ObxCommand cmd );
OBEX_EXPORT ObxObject*     ObxObjectNewResponse( ObxHandle *handle, ObxObject *request, ObxCommand cmd );

OBEX_EXPORT ObxRc          ObxObjectFree( ObxHandle *handle, ObxObject *object );
OBEX_EXPORT ObxRc          ObxObjectReset( ObxObject *object );
OBEX_EXPORT ObxRc          ObxObjectAddHeader( ObxHandle *handle, ObxObject *object, ObxHeader *header );
OBEX_EXPORT ObxList        *ObxObjectGetHeaderList( ObxObject *object );
OBEX_EXPORT ObxCommand     ObxObjectGetCommand( ObxObject *object );

/*
**************************************************************************
**
** Obex headers
**
** ObxHeaderNew()
**    Create a new header.
**
** ObxHeaderSetIntValue()
**    On headers where an int value is appropriate, this method sets the value.
**
** ObxHeaderSetByteValue()
**    On headers where an byte value is appropriate, this method sets the value.
**
** ObxHeaderSetUnicodeValue()
**    On headers where an unicode value is appropriate, this method sets the value.
**    Ownership of the passed ObxBuffer is assumed by the header.
**
** ObxHeaderSetByteSequenceValue()
**    On headers where an bytestream value is appropriate, this method sets the value.
**    Ownership of the passed ObxBuffer is assumed by the header.
**
** ObxHeaderNewFromBuffer()
**    Builds a header from a passed ObxBuffer object.  Note that any lengths within
**    the buffer are assumed to be in network byte order.
**    If autoAppend is TRUE, the passed object will be searched for existing headers
**    of the same type.  If found, the data will be appended to this header and a NULL
**    will be returned.
**
** ObxHeaderFree()
**    Frees all contents (and the header itself).
**
** ObxHeaderSize()
**    Returns the header size.  The size includes the opcode and any required lengths
**    in addition to the data itself.
**
** ObxAddHeader():
**    Associates the passed header with the passed object within the passed handle.
**
** ObxGetHeaderList():
**    Returns a list construct containing the headers.
**
**************************************************************************
*/
OBEX_EXPORT ObxHeader   *ObxHeaderNew( unsigned char opcode );

OBEX_EXPORT ObxRc       ObxHeaderSetIntValue( ObxHeader *header, unsigned int value );
OBEX_EXPORT ObxRc       ObxHeaderSetByteValue( ObxHeader *header, unsigned char value );
OBEX_EXPORT ObxRc       ObxHeaderSetUnicodeValue( ObxHeader *header, ObxBuffer *value );
OBEX_EXPORT ObxRc       ObxHeaderSetByteSequenceValue( ObxHeader *header, ObxBuffer *value );

OBEX_EXPORT ObxHeader   *ObxHeaderNewFromBuffer( ObxBuffer *buffer, ObxObject *object );
OBEX_EXPORT void        ObxHeaderFree( ObxHeader *header );
OBEX_EXPORT int         ObxHeaderSize( ObxHeader *header );

OBEX_EXPORT ObxRc       ObxHeaderAdd( ObxHandle *handle, ObxObject *object, ObxHeader *header );
OBEX_EXPORT ObxList*    ObxGetHeaderList( ObxHandle *handle, ObxObject *object );


/*
**************************************************************************
**
** Obex buffers
**
** ObxBufNew()
**    Alloc a new buffer of specified length.
**    Returns a newly allocated ObxBuffer or NULL on error.
**
** ObxBufFree()
**    Free all internal contents and the 'buf' itself.
**    Pointer 'buf' should not be used after calling this function.
**
** ObxBufReset()
**    Clear internal state, allows buffer to be reused.
**    Returns a reset ObxBuffer or NULL on error.
**
** ObxBufWrite()
**    Appends bytes from passed 'data' to the end of the
**    buffer.  (copies data from 'data' into buffer).
**    Returns 0 on success, !0 on error.
**
** ObxBufRead()
**    Populates 'data' with 'len' bytes from the buffer.  Returns
**    the actual number of bytes placed into 'data'.  This value can
**    be less than 'len' if no additional bytes were available.
**    Data is consumed by this call (not available for read again).
**
** ObxBufPeek()
**    Populates 'data' with 'len' bytes from the buffer.  Returns
**    the actual number of bytes placed into 'data'.  This value can
**    be less than 'len' if no additional bytes were available.
**    Data is NOT consumed by this call.
**
** ObxBufSize()
**    Number of unread bytes in buffer.
**
*/
OBEX_EXPORT ObxBuffer   *ObxBufNew( int len );
OBEX_EXPORT void        ObxBufFree( ObxBuffer *buf );
OBEX_EXPORT ObxBuffer   *ObxBufReset( ObxBuffer *buf );
OBEX_EXPORT int         ObxBufWrite( ObxBuffer *buf, void *data, int len );
OBEX_EXPORT int         ObxBufRead( ObxBuffer *buf, void *data, int len );
OBEX_EXPORT int         ObxBufPeek( ObxBuffer *buf, void *data, int len );
OBEX_EXPORT int         ObxBufSize( ObxBuffer *buf );

/*
**************************************************************************
**
** Obex lists
**
** ObxListNew()
**    Create a new list.
**
** ObxListFree()
**    Free's the contents of a list and the list struct itself.
**    WARNING: each element of the list is also free()'ed!
**    Use ObxListRelease() to remove the elements without freeing them.
**    The list should be considered invalid after this call.
**
** ObxListReset()
**    Empty's the list, free()'ing all elements and resetting the list
**    to it's initial state.
**    The list is still viable and ready for use after this call.
**    Use ObxListFree() to free the list itself.
**
** ObxListRelease()
**    Removes all contents of a list.  They are not free'ed.  It's assumed
**    that the caller is managing their storage.
**    The list is still viable and ready for use after this call.
**
** ObxListAppend()
**    Append a new data to the end of the list
**    On success, returns void * pointing to the data that was added.
**    Returns NULL on error.
**
** ObxListGetIterator()
**    Get an Iterator for the list.
**    Returns the newly created iterator or NULL on error.
**
** ObxListInsert()
**    Insert a new element into the list 'after' the current position of
**    the Iterator.
**    Inserts to the front of the list are done with an iterator that has been
**    'reset' (ObxIteratorReset()).
**    On success, returns pointer to the data that was added.
**    Returns NULL on error.
**
** ObxListRemove()
**    Remove the element being pointed to by the iterator.  Return this data
**    as a pointer to the caller.
**
**    The iterator is adjusted as follows:
**    1) The iterator is backed up to the previous node.
**    2) If the node being removed was the first node, the iterator is reset.
**
**    On success, returns pointer to the data that was removed.
**    Returns NULL on error.
**
**    Use ObxListDelete() to remove and free the data being managed by the
**    list.
**
** ObxListDelete()
**    Remove the element being pointed to by the iterator.  Free any data associated
**    with the node.
**
**    The iterator is adjusted as follows:
**    1) The iterator is backed up to the previous node.
**    2) If the node being removed was the first node, the iterator is reset.
**
**    Use ObxListRemove() to remove the data and return it to the caller.
**
** ObxIteratorReset()
**    Reset the enumeration cursor to the beginning of the list.
**    Returns the newly reset iterator or NULL on error.
**
** ObxIteratorFree()
**    Free storage associated with the Iterator.  Iterator should be considered
**    invalid after this call.
**
** ObxIteratorNext()
**    Requests the next element of data.  If at the end of the list, list is empty
**    or the passed iterator is NULL, NULL is returned.
**
** ObxIteratorHasNext()
**    Queries the existence of an element beyond the current element in
**    the list.  Returns 0 if one does not exist, non-zero otherwise.
**
**************************************************************************
*/
OBEX_EXPORT ObxList     *ObxListNew();
OBEX_EXPORT void        ObxListFree( ObxList *list );
OBEX_EXPORT void        ObxListReset( ObxList *list );
OBEX_EXPORT void        ObxListRelease( ObxList *list );
OBEX_EXPORT void        *ObxListAppend( ObxList *list, void *data );
OBEX_EXPORT void        *ObxListInsert( ObxList *list, const ObxIterator *iterator, void *data );
OBEX_EXPORT void        *ObxListRemove( ObxList *list, ObxIterator *iterator );
OBEX_EXPORT void        ObxListDelete( ObxList *list, ObxIterator *iterator );

OBEX_EXPORT ObxIterator *ObxListGetIterator( ObxList *list );
OBEX_EXPORT ObxIterator *ObxIteratorReset( ObxIterator *iterator );
OBEX_EXPORT void        ObxIteratorFree( ObxIterator *iterator );
OBEX_EXPORT void        *ObxIteratorNext( ObxIterator *iterator );
OBEX_EXPORT short       ObxIteratorHasNext( ObxIterator *iterator );

/*
**************************************************************************
**
** Misc conversion functions
**
** ObxUnicodeToUTF8()
**    Converts the passed buffer Unicode to UTF8.  The length indicates the
**    length of the unicode buffer.
**    The result is present in the ObxBuffer structure returned.
**    NULL is returned on error.
**
** ObxUTF8ToUnicode()
**    Converts the passed buffer, which points to a buffer containing
**    UTF8, to Unicode.  The length represents the length of the passed buffer.
**    The result is present in the ObxBuffer structure returned.  NULL is returned on error.
**
**************************************************************************
*/
OBEX_EXPORT ObxBuffer   *ObxUnicodeToUTF8( const unsigned char *unicodeBuffer, int ucLength );
OBEX_EXPORT ObxBuffer   *ObxUTF8ToUnicode( const unsigned char *utf8Buffer, int utf8Length );

#ifdef __cplusplus
}
#endif

#endif