Ensure IrOBEX_TransportConnect() returns error if it fails.
[openobex:mainline.git] / lib / api.c
1 /**
2         \file api.c
3         OpenOBEX API definition.
4         OpenOBEX library - Free implementation of the Object Exchange protocol.
5
6         Copyright (c) 1999, 2000 Dag Brattli, All Rights Reserved.
7         Copyright (c) 1999, 2000 Pontus Fuchs, All Rights Reserved.
8
9         OpenOBEX is free software; you can redistribute it and/or modify
10         it under the terms of the GNU Lesser General Public License as
11         published by the Free Software Foundation; either version 2.1 of
12         the License, or (at your option) any later version.
13
14         This program is distributed in the hope that it will be useful,
15         but WITHOUT ANY WARRANTY; without even the implied warranty of
16         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17         GNU Lesser General Public License for more details.
18
19         You should have received a copy of the GNU Lesser General Public
20         License along with OpenOBEX. If not, see <http://www.gnu.org/>.
21  */
22
23 #ifdef HAVE_CONFIG_H
24 #include <config.h>
25 #endif
26
27 #ifdef _WIN32
28 #include <winsock2.h>
29 #include <windows.h>
30 #ifndef ESOCKTNOSUPPORT
31 #define ESOCKTNOSUPPORT WSAESOCKTNOSUPPORT
32 #endif
33
34 #else /* _WIN32 */
35 #include <fcntl.h>
36 #include <unistd.h>
37 #endif /* _WIN32 */
38
39 #include <stdio.h>
40 #include <stdlib.h>
41 #include <string.h>
42 #include <errno.h>
43
44 #include "obex_main.h"
45 #include "obex_client.h"
46 #include "obex_object.h"
47 #include "obex_body.h"
48 #include "obex_msg.h"
49 #include "obex_connect.h"
50 #include "databuffer.h"
51
52 #ifdef HAVE_IRDA
53 #include "transport/irobex.h"
54 #endif /*HAVE_IRDA*/
55 #ifdef HAVE_BLUETOOTH
56 #include "transport/btobex.h"
57 #endif /*HAVE_BLUETOOTH*/
58 #ifdef HAVE_USB
59 #include "transport/usbobex.h"
60 #endif /*HAVE_USB*/
61 #include "transport/inobex.h"
62 #include "transport/customtrans.h"
63 #include "transport/fdobex.h"
64
65 #include "obex_incl.h"
66
67 /**
68         Initialize OBEX.
69         \param transport Which transport to use. The following transports are available :
70                         - #OBEX_TRANS_IRDA : Use regular IrDA socket (need an IrDA stack)
71                         - #OBEX_TRANS_INET : Use regular TCP/IP socket
72                         - #OBEX_TRANS_CUSTOM : Use user provided transport, you must
73                         register your own transport with #OBEX_RegisterCTransport()
74                         - #OBEX_TRANS_BLUETOOTH: Use regular Bluetooth RFCOMM socket
75                         - #OBEX_TRANS_USB: Use USB transport (libusb needed)
76         \param eventcb Function pointer to your event callback.
77                         See obex.h for prototype of this callback.
78         \param flags Bitmask of flags. The following flags are available :
79                         - #OBEX_FL_KEEPSERVER : Keep the server alive after incomming request
80                         - #OBEX_FL_FILTERHINT : Filter target devices based on Obex hint bit
81                         - #OBEX_FL_FILTERIAS  : Filter target devices based on IAS entry
82                         - #OBEX_FL_CLOEXEC    : Open all sockets with SO_CLOEXEC set
83                         - #OBEX_FL_NONBLOCK   : Open all sockets non-blocking
84         \return an OBEX handle or NULL on error.
85  */
86 LIB_SYMBOL
87 obex_t * CALLAPI OBEX_Init(int transport, obex_event_t eventcb,
88                                                         unsigned int flags)
89 {
90         obex_t *self;
91
92         obex_return_val_if_fail(eventcb != NULL, NULL);
93
94         obex_library_init();
95         self = obex_create(eventcb, flags);
96         if (!obex_transport_init(self, transport)) {
97                 obex_destroy(self);
98                 self = NULL;
99         }
100
101         return self;
102 }
103
104 /**
105         Register a custom transport.
106         \param self OBEX handle
107         \param ctrans Structure with callbacks to transport operations
108                 (see obex_const.h for details)
109         \return -1 on error
110
111         Call this function directly after #OBEX_Init if you are using
112         a custom transport.
113  */
114 LIB_SYMBOL
115 int CALLAPI OBEX_RegisterCTransport(obex_t *self, obex_ctrans_t *ctrans)
116 {
117         obex_return_val_if_fail(self != NULL, -1);
118         obex_return_val_if_fail(ctrans != NULL, -1);
119
120         return custom_register(self, ctrans);
121 }
122
123 /**
124         Close down an OBEX instance.
125         \param self OBEX handle
126
127         Disconnects the transport and frees the interface (see
128         #OBEX_FreeInterfaces).
129  */
130 LIB_SYMBOL
131 void CALLAPI OBEX_Cleanup(obex_t *self)
132 {
133         obex_return_if_fail(self != NULL);
134
135         obex_destroy(self);
136 }
137
138 /**
139         Set userdata of an OBEX handle.
140         \param self OBEX handle
141         \param data It's all up to you!
142  */
143 LIB_SYMBOL
144 void CALLAPI OBEX_SetUserData(obex_t *self, void *data)
145 {
146         obex_return_if_fail(self != NULL);
147         self->userdata=data;
148 }
149
150 /**
151         Read the userdata from an OBEX handle.
152         \param self OBEX handle
153         \return the userdata
154
155         Returns userdata set with #OBEX_SetUserData.
156  */
157 LIB_SYMBOL
158 void * CALLAPI OBEX_GetUserData(obex_t *self)
159 {
160         obex_return_val_if_fail(self != NULL, 0);
161         return self->userdata;
162 }
163
164 /**
165         Change user callback on an OBEX handle.
166         \param self OBEX handle
167         \param eventcb Function pointer to your new event callback.
168         \param data Pointer to the new user data to pass to the new
169         callback (optional)
170  */
171 LIB_SYMBOL
172 void CALLAPI OBEX_SetUserCallBack(obex_t *self, obex_event_t eventcb,
173                                                                 void *data)
174 {
175         obex_return_if_fail(self != NULL);
176         /* The callback can't be NULL */
177         if (eventcb != NULL) {
178                 self->eventcb = eventcb;
179                 /* Optionaly change the user data */
180                 if (data != NULL)
181                         self->userdata = data;
182         }
183 }
184
185 /**
186         Set MTU to be used for receive and transmit.
187         \param self OBEX handle
188         \param mtu_rx maximum receive transport packet size
189         \param mtu_tx_max maximum transmit transport packet size negociated
190         \return -1 or negative error code on error
191
192         Changing those values can increase the performance of the underlying
193         transport, but will increase memory consumption and latency (especially
194         abort latency), and may trigger bugs in buggy transport.
195         This need to be set *before* establishing the connection.
196  */
197 LIB_SYMBOL
198 int CALLAPI OBEX_SetTransportMTU(obex_t *self, uint16_t mtu_rx,
199                                                         uint16_t mtu_tx_max)
200 {
201         obex_return_val_if_fail(self != NULL, -EFAULT);
202         if (self->object) {
203                 DEBUG(1, "We are busy.\n");
204                 return -EBUSY;
205         }
206
207         return obex_set_mtu(self, mtu_rx, mtu_tx_max);
208 }
209
210 /**
211         Start listening for incoming connections.
212         \param self OBEX handle
213         \param saddr Local address to bind to or NULL
214         \param addrlen Length of address
215         \return -1 on error
216
217         Bind a server socket to an Obex service. Common transport have
218         specialised version of this function.
219         If you want to call the listen callback of the custom transport,
220         use NULL for saddr and 0 for addrlen.
221  */
222 LIB_SYMBOL
223 int CALLAPI OBEX_ServerRegister(obex_t *self, struct sockaddr *saddr, int addrlen)
224 {
225         DEBUG(3, "\n");
226
227         obex_return_val_if_fail(self != NULL, -1);
228         obex_return_val_if_fail((addrlen == 0) || (saddr != NULL), -1);
229
230         if (addrlen != 0 && saddr != NULL &&
231             !obex_transport_set_local_addr(self, saddr, addrlen))
232                 return -1;
233
234         return obex_transport_listen(self)? 1: -1;
235 }
236
237 /**
238         Accept an incoming connection.
239         \param server OBEX handle
240         \param eventcb Event callback for client (use NULL for same as server)
241         \param data Userdata for client (use NULL for same as server)
242         \return the client instance or NULL on error
243
244         Create a new OBEX instance to handle the incomming connection.
245         The old OBEX instance will continue to listen for new connections.
246         The two OBEX instances become totally independant from each other.
247
248         This function should be called after the library generates
249         an #OBEX_EV_ACCEPTHINT event to the user, but before the user
250         start to pull data out of the incomming connection.
251
252         Using this function also requires that the OBEX handle was created
253         with the #OBEX_FL_KEEPSERVER flag set while calling #OBEX_Init().
254  */
255 LIB_SYMBOL
256 obex_t *CALLAPI OBEX_ServerAccept(obex_t *server, obex_event_t eventcb,
257                                                                 void *data)
258 {
259         obex_t *self;
260
261         DEBUG(3, "\n");
262
263         obex_return_val_if_fail(server != NULL, NULL);
264
265         /* If we have started receiving something, it's too late... */
266         if (server->object != NULL)
267                 return NULL;
268
269         /* Set callback and callback data as needed */
270         if (eventcb == NULL)
271                 eventcb = server->eventcb;
272         if (data == NULL)
273                 data = server->userdata;
274
275         /* Allocate new instance */
276         self = obex_create(eventcb, server->init_flags);
277         if (self == NULL)
278                 return NULL;
279
280         self->userdata = data;
281         if (!obex_transport_accept(self, server))
282                 goto out_err;
283
284         self->mtu_tx = server->mtu_tx;
285         if (obex_set_mtu(self, server->mtu_rx, server->mtu_tx_max))
286                 goto out_err;
287
288         self->mode = OBEX_MODE_SERVER;
289         self->state = STATE_IDLE;
290         self->rsp_mode = server->rsp_mode;
291
292         return self;
293
294 out_err:
295         obex_destroy(self);
296         return NULL;
297 }
298
299 /**
300         Set the timeout for read/write operations if supported by the underlying
301         transport.
302         \param self OBEX handle
303         \param timeout Maximum time to wait in milliseconds (-1 for infinite)
304  */
305 LIB_SYMBOL
306 void CALLAPI OBEX_SetTimeout(obex_t *self, int64_t timeout)
307 {
308         obex_return_if_fail(self != NULL);
309         obex_transport_set_timeout(self, timeout);      
310 }
311
312 /**
313         Let the OBEX parser do some work.
314         \param self OBEX handle
315         \return -1 on error, 0 on timeout, positive on success
316
317         Let the OBEX parser read and process incoming data, or prepare and send
318         outgoing data.
319
320         When a request has been sent (client) or you are waiting for an incoming
321         request (server) you should call this function until the request has
322         finished.
323  */
324 LIB_SYMBOL
325 int CALLAPI OBEX_Work(obex_t *self)
326 {
327         DEBUG(4, "\n");
328         obex_return_val_if_fail(self != NULL, -1);
329         return obex_work(self);
330 }
331
332 /**
333         Determine data direction of OBEX_Work()
334         \param self OBEX handle
335
336         Use this to achieve better integration of OBEX_Work() into mainloops.
337         You should call this after each call of OBEX_Work().
338         If #OBEX_DATA_NONE is returned, it depends on your event callback when
339         to re-enable mainloop events.
340  */
341 LIB_SYMBOL
342 enum obex_data_direction CALLAPI OBEX_GetDataDirection(obex_t *self)
343 {
344         DEBUG(4, "\n");
345         return obex_get_data_direction(self);
346 }
347
348 /**
349         Let the OBEX parser do some work.
350         \param self OBEX handle
351         \param timeout Maximum time to wait in seconds (-1 for infinite)
352         \return -1 on error, 0 on timeout, positive on success
353
354         Deprecated.
355
356         Let the OBEX parser read and process incoming data and send the response.
357
358         The timeout parameter is only for the reading part, preparing and sending
359         can take any amount of time.
360  */
361 LIB_SYMBOL
362 int CALLAPI OBEX_HandleInput(obex_t *self, int timeout)
363 {
364         int result;
365         int64_t oldTimeout;
366         enum obex_data_direction dir;
367
368         obex_return_val_if_fail(self != NULL, -1);
369
370         DEBUG(4, "\n");
371
372         oldTimeout = obex_transport_get_timeout(self);
373         dir = obex_get_data_direction(self);
374         obex_transport_set_timeout(self, timeout*1000);
375
376         if (dir == OBEX_DATA_IN) {
377                 result = obex_work(self);
378                 if (result <= 0) /* timeout or error */
379                         goto timeout_or_error;
380                 dir = obex_get_data_direction(self);
381         }
382
383         /* make the following loop more efficient */
384         obex_transport_set_timeout(self, -1);
385
386         while (dir == OBEX_DATA_NONE || dir == OBEX_DATA_OUT) {
387                 result = obex_work(self);
388                 if (result < 0) /* error */
389                         goto timeout_or_error;
390                 dir = obex_get_data_direction(self);
391         }
392
393         result = 1;
394
395 timeout_or_error:
396         obex_transport_set_timeout(self, oldTimeout);
397         return result;
398 }
399
400 /**
401         Feed OBEX with data when using a custom transport.
402         \param self OBEX handle
403         \param inputbuf Pointer to custom data
404         \param actual Length of buffer
405         \return -1 on error
406  */
407 LIB_SYMBOL
408 int CALLAPI OBEX_CustomDataFeed(obex_t *self, uint8_t *inputbuf, int actual)
409 {
410         DEBUG(3, "\n");
411
412         obex_return_val_if_fail(self != NULL, -1);
413
414         if (inputbuf && actual > 0)
415                 buf_append(self->rx_msg, inputbuf, (size_t)actual);
416
417         return obex_data_indication(self);
418 }
419
420 /**
421         Try to connect to peer.
422         \param self OBEX handle
423         \param saddr Address to connect to
424         \param addrlen Length of address
425         \return -1 on error
426  */
427 LIB_SYMBOL
428 int CALLAPI OBEX_TransportConnect(obex_t *self, struct sockaddr *saddr, int addrlen)
429 {
430         DEBUG(4, "\n");
431
432         obex_return_val_if_fail(self != NULL, -1);
433         obex_return_val_if_fail((addrlen == 0) || (saddr != NULL), -1);
434
435         if (addrlen != 0 && saddr != NULL &&
436             !obex_transport_set_remote_addr(self, saddr, addrlen))
437                 return -1;
438
439         return obex_transport_connect_request(self)? 1: -1;
440 }
441
442 /**
443         Disconnect transport.
444         \param self OBEX handle
445         \return -1 on error
446  */
447 LIB_SYMBOL
448 int CALLAPI OBEX_TransportDisconnect(obex_t *self)
449 {
450         DEBUG(4, "\n");
451         obex_return_val_if_fail(self != NULL, -1);
452
453         obex_transport_disconnect(self);
454
455         return 0;
456 }
457
458 /**
459         Get transport file descriptor.
460         \param self OBEX handle
461         \return file descriptor of the transport, -1 on error
462
463         Returns the file descriptor of the transport or -1 on error.
464         Note that not all transports have a file descriptor, especially
465         USB and custom transports do not.
466
467         The returned filehandle can be used to do select() on, before
468         calling OBEX_HandleInput()
469
470         There is one subtelty about this function. When the OBEX connection is
471         established, it returns the connection filedescriptor, while for
472         an unconnected server it will return the listening filedescriptor.
473         This mean that after receiving an incomming connection, you need to
474         call this function again.
475  */
476 LIB_SYMBOL
477 int CALLAPI OBEX_GetFD(obex_t *self)
478 {
479         obex_return_val_if_fail(self != NULL, -1);
480
481         return obex_transport_get_fd(self);
482 }
483
484 /**
485         Schedule a request (as client).
486         \param self OBEX handle
487         \param object Object containing request
488         \return 0 on success or a negative error code on failure (-EBUSY, -EINVAL, -EIO)
489  */
490 LIB_SYMBOL
491 int CALLAPI OBEX_Request(obex_t *self, obex_object_t *object)
492 {
493         result_t result;
494
495         DEBUG(4, "\n");
496
497         obex_return_val_if_fail(self != NULL, -EINVAL);
498         obex_return_val_if_fail(object != NULL, -EINVAL);
499
500         if (self->object) {
501                 DEBUG(1, "We are busy.\n");
502                 return -EBUSY;
503         }
504
505         object->rsp_mode = self->rsp_mode;
506         self->object = object;
507         self->mode = OBEX_MODE_CLIENT;
508         self->state = STATE_REQUEST;
509         self->substate = SUBSTATE_TX_PREPARE;
510
511         /* Prepare the packet but do not send it */
512         result = obex_client(self);
513         if (result < 0) {
514                 self->object = NULL;
515                 self->mode = OBEX_MODE_SERVER;
516                 self->state = STATE_IDLE;
517                 return -EIO;
518         }
519
520         return 0;
521 }
522
523 /**
524         Cancel an ongoing operation.
525         \param self OBEX handle
526         \param nice If true an OBEX Abort will be sent if beeing client
527         or respond with an error if beeing server.
528         \return -1 on error
529  */
530 LIB_SYMBOL
531 int CALLAPI OBEX_CancelRequest(obex_t *self, int nice)
532 {
533         obex_return_val_if_fail(self != NULL, -1);
534         return obex_cancelrequest(self, nice);
535 }
536
537 /**
538         Suspend transfer of an object.
539         \param self OBEX handle
540         \param object object to suspend (NULL to suspend currently transfered object)
541         \return -1 on error
542  */
543 LIB_SYMBOL
544 int CALLAPI OBEX_SuspendRequest(obex_t *self, obex_object_t *object)
545 {
546         obex_return_val_if_fail(object != NULL || self->object != NULL, -1);
547         return obex_object_suspend(object ? object : self->object);
548 }
549
550 /**
551         Resume transfer of an object.
552         \param self OBEX handle
553         \return -1 on error
554  */
555 LIB_SYMBOL
556 int CALLAPI OBEX_ResumeRequest(obex_t *self)
557 {
558         obex_return_val_if_fail(self->object != NULL, -1);
559         return obex_object_resume(self->object);
560 }
561
562 /**
563         Set the OBEX response mode.
564         \param self OBEX context
565         \param rsp_mode see OBEX_RSP_MODE_*
566
567         If you want any mode other than default (#OBEX_RSP_MODE_NORMAL), you
568         have to call this function. If you want it to affect the current object,
569         you need to call it at the first #OBEX_EV_PROGRESS (as client) or
570         at the #OBEX_EV_REQHINT or #OBEX_EV_REQCHECK events (as server).
571  */
572 LIB_SYMBOL
573 void CALLAPI OBEX_SetReponseMode(obex_t *self, enum obex_rsp_mode rsp_mode)
574 {
575         switch (rsp_mode) {
576         case OBEX_RSP_MODE_NORMAL:
577         case OBEX_RSP_MODE_SINGLE:
578                 self->rsp_mode = rsp_mode;
579                 if (self->object)
580                         self->object->rsp_mode = rsp_mode;
581                 break;
582
583         default:
584                 break;
585         }
586 }
587
588 /**
589         Create a new OBEX Object.
590         \param self OBEX handle
591         \param cmd command of object
592         \return pointer to a new OBEX Object, NULL on error
593  */
594 LIB_SYMBOL
595 obex_object_t * CALLAPI OBEX_ObjectNew(obex_t *self, uint8_t cmd)
596 {
597         obex_object_t *object;
598
599         obex_return_val_if_fail(self != NULL, NULL);
600
601         object = obex_object_new();
602         if (object == NULL)
603                 return NULL;
604
605         obex_object_setcmd(object, cmd);
606         /* Need some special woodoo magic on connect-frame */
607         if (cmd == OBEX_CMD_CONNECT) {
608                 if (obex_insert_connectframe(self, object) < 0) {
609                         obex_object_delete(object);
610                         object = NULL;
611                 }
612         }
613
614         return object;
615 }
616
617 /**
618         Delete an OBEX object.
619         \param self OBEX handle
620         \param object object to delete.
621         \return -1 on error
622
623         Note that as soon as you have passed an object to the lib using
624         OBEX_Request(), you shall not delete it yourself.
625  */
626 LIB_SYMBOL
627 int CALLAPI OBEX_ObjectDelete(obex_t *self, obex_object_t *object)
628 {
629         obex_return_val_if_fail(object != NULL, -1);
630         return obex_object_delete(object);
631 }
632
633 /**
634         Get available space in object.
635         \param self OBEX handle
636         \param object OBEX object to query
637         \param flags OBEX_FL_FIT_ONE_PACKET or 0
638         \return -1 on error
639
640         Returns the available space in a given obex object.
641
642         This can be useful e.g. if the caller wants to check the size of the
643         biggest body header that can be added to the current packet.
644
645  */
646 LIB_SYMBOL
647 int CALLAPI OBEX_ObjectGetSpace(obex_t *self, obex_object_t *object,
648                                 unsigned int flags)
649 {
650         obex_return_val_if_fail(self != NULL, -1);
651         obex_return_val_if_fail(object != NULL, -1);
652         return obex_msg_getspace(self, object, flags);
653 }
654
655 /**
656         Attach a header to an object.
657         \param self OBEX handle
658         \param object OBEX object
659         \param hi Header identifier
660         \param hv Header value
661         \param hv_size Header size
662         \param flags See obex.h for possible values
663         \return -1 on error
664
665         Add a new header to an object.
666
667         If you want all headers to fit in one packet, use the flag
668         #OBEX_FL_FIT_ONE_PACKET on all headers you add to an object.
669
670         To stream a body add a body header with hv.bs = NULL and set the flag
671         #OBEX_FL_STREAM_START. You will now get #OBEX_EV_STREAMEMPTY events as
672         soon as the the parser wants you to feed it with more data.
673
674         When you get an #OBEX_EV_STREAMEMPTY event give the parser some data by
675         adding a body-header and set the flag #OBEX_FL_STREAM_DATA. When you
676         have no more data to send set the flag #OBEX_FL_STREAM_DATAEND instead.
677
678         After adding a header you are free to do whatever you want with
679         the buffer if you are NOT streaming. If you are streaming you
680         may not touch the buffer until you get another
681         #OBEX_EV_STREAMEMPTY or until the request finishes.
682
683         The headers will be sent in the order you add them.
684  */
685 LIB_SYMBOL
686 int CALLAPI OBEX_ObjectAddHeader(obex_t *self, obex_object_t *object, uint8_t hi,
687                                 obex_headerdata_t hv, uint32_t hv_size,
688                                 unsigned int flags)
689 {
690         obex_return_val_if_fail(self != NULL, -1);
691         obex_return_val_if_fail(object != NULL, -1);
692         return obex_object_addheader(self, object, hi, hv, hv_size, flags);
693 }
694
695 /**
696         Get next available header from an object.
697         \param self OBEX handle (ignored)
698         \param object OBEX object
699         \param hi Pointer to header identifier
700         \param hv Pointer to hv
701         \param hv_size Pointer to hv_size
702         \return 0 when no more headers are available, -1 on error
703
704         Returns 0 when no more headers are available.
705
706         All headers are read-only.
707
708         You will get the headers in the received order.
709  */
710 LIB_SYMBOL
711 int CALLAPI OBEX_ObjectGetNextHeader(obex_t *self, obex_object_t *object, uint8_t *hi,
712                                         obex_headerdata_t *hv,
713                                         uint32_t *hv_size)
714 {
715         obex_return_val_if_fail(object != NULL, -1);
716         return obex_object_getnextheader(object, hi, hv, hv_size);
717 }
718
719 /**
720         Allow the user to parse again the rx headers.
721         \param self OBEX handle (ignored)
722         \param object OBEX object
723         \return 1 on success, 0 if previous parsing not completed, -1 on error
724
725         Next call to #OBEX_ObjectGetNextHeader() will return the first received
726         header.
727  */
728 LIB_SYMBOL
729 int CALLAPI OBEX_ObjectReParseHeaders(obex_t *self, obex_object_t *object)
730 {
731         obex_return_val_if_fail(object != NULL, -1);
732         return obex_object_reparseheaders(object);
733 }
734
735 /**
736         Read data from body stream.
737         \param self OBEX handle
738         \param object OBEX object (ignored)
739         \param buf A pointer to a pointer which this function will set
740         to a buffer which shall be read (and ONLY read) after this
741         function returns.
742         \return number of bytes in buffer, or 0 for end-of-stream, -1 on error
743
744         To recieve the body as a stream call this function with buf = NULL
745         as soon as you get an #OBEX_EV_REQHINT event.
746
747         You will now recieve #OBEX_EV_STREAMAVAIL events when data is
748         available for you. Call this function to get the data.
749
750         Note! When receiving a stream data is not buffered so if you
751         don't call this function when you get an #OBEX_EV_STREAMAVAIL
752         event data will be lost.
753  */
754 LIB_SYMBOL
755 int CALLAPI OBEX_ObjectReadStream(obex_t *self, obex_object_t *object,
756                                                         const uint8_t **buf)
757 {
758         size_t size = 0;
759
760         obex_return_val_if_fail(self != NULL, -1);
761
762         object = self->object;
763         obex_return_val_if_fail(object != NULL, -1);
764
765         /* Enable streaming */
766         if (buf == NULL) {
767                 struct obex_body *b = obex_body_stream_create(self);
768                 int result = obex_object_set_body_receiver(object, b);
769
770                 if (!result)
771                         return -1;
772                 DEBUG(4, "Streaming is enabled!\n");
773                 return 0;
774         }
775
776         if (buf)
777                 *buf = obex_object_read_body(object, &size);
778
779         return (int)size;
780 }
781
782 /**
783         Sets the response to a received request.
784         \param object OBEX object
785         \param rsp Respose code in non-last packets
786         \param lastrsp Response code in last packet
787         \return -1 on error
788  */
789 LIB_SYMBOL
790 int CALLAPI OBEX_ObjectSetRsp(obex_object_t *object, uint8_t rsp,
791                                                         uint8_t lastrsp)
792 {
793         obex_return_val_if_fail(object != NULL, -1);
794         return obex_object_setrsp(object, rsp, lastrsp);
795 }
796
797 /**
798         Get any data which was before headers.
799         \param object OBEX object
800         \param buffer Pointer to a pointer which will point to a
801         read-only buffer
802         \return size of the buffer or -1 for error
803  */
804 LIB_SYMBOL
805 int CALLAPI OBEX_ObjectGetNonHdrData(obex_object_t *object, uint8_t **buffer)
806 {
807         obex_return_val_if_fail(object != NULL, -1);
808         if (!object->rx_nonhdr_data)
809                 return 0;
810
811         *buffer = buf_get(object->rx_nonhdr_data);
812         return buf_get_length(object->rx_nonhdr_data);
813 }
814
815 /**
816         Set data to send before headers.
817         \param object OBEX object
818         \param buffer Data to send
819         \param len Length to data
820         \return 1 on success, -1 on error
821
822         Some commands (notably SetPath) send data before headers. Use this
823         function to set this data.
824  */
825 LIB_SYMBOL
826 int CALLAPI OBEX_ObjectSetNonHdrData(obex_object_t *object,
827                                                 const uint8_t *buffer,
828                                                 unsigned int len)
829 {
830         /* TODO: Check that we actually can send len bytes without
831          * violating MTU */
832
833         obex_return_val_if_fail(object != NULL, -1);
834         obex_return_val_if_fail(buffer != NULL, -1);
835
836         if (object->tx_nonhdr_data)
837                 return -1;
838
839         object->tx_nonhdr_data = membuf_create(len);
840         if (object->tx_nonhdr_data == NULL)
841                 return -1;
842
843         buf_append(object->tx_nonhdr_data, buffer, len);
844
845         return 1;
846 }
847
848 /**
849         Set headeroffset.
850         \param object OBEX object
851         \param offset Desired offset
852         \return 1 on success, -1 on error
853
854         Call this function when you get a OBEX_EV_REQHINT and you know that the
855         command has data before the headers comes. You do NOT need to use this
856         function on Connect and SetPath, they are handled automatically.
857  */
858 LIB_SYMBOL
859 int CALLAPI OBEX_ObjectSetHdrOffset(obex_object_t *object, unsigned int offset)
860 {
861         obex_return_val_if_fail(object != NULL, -1);
862         object->headeroffset = offset;
863         return 1;
864 }
865
866 /**
867         Get the OBEX commmand of an object.
868         \param self OBEX context
869         \param object OBEX object (or NULL to access the current object)
870         \return -1 on error
871
872         Call this function to get the OBEX command of an object.
873  */
874 LIB_SYMBOL
875 int CALLAPI OBEX_ObjectGetCommand(obex_t *self, obex_object_t *object)
876 {
877         obex_return_val_if_fail(object != NULL || self->object != NULL, -1);
878
879         if (object)
880                 return object->cmd;
881
882         return self->object->cmd;
883 }
884
885 /**
886         Return a human understandable string from a response-code.
887         \param rsp Response code.
888         \return static response code string
889
890         The returned string must not be freed.
891         If the response code is unknown, the string "Unknown response" will
892         be returned.
893  */
894 LIB_SYMBOL
895 char * CALLAPI OBEX_ResponseToString(int rsp)
896 {
897         DEBUG(4, "\n");
898
899         return obex_response_to_string(rsp);
900 }
901
902 /**
903         Set customdata of an OBEX handle.
904         \param self OBEX handle
905         \param data Custom Transport data
906         \return 0 on success, -1 on error
907
908         Note : this call is *reserved* to the Custom Transport and
909         should not be use by the user/client. It allow to update the
910         Custom Transport data originally set via
911         OBEX_RegisterCTransport().
912         The Custom Transport data (or instance handle) is used to store
913         data relative to the specific instance (i.e. connection), such
914         as file descriptors, offsets and others, so that the Custom
915         Transport can manage multiple connections transparently (i.e.
916         without a lookup table).
917         - Jean II
918  */
919 LIB_SYMBOL
920 int CALLAPI OBEX_SetCustomData(obex_t *self, void *data)
921 {
922         obex_return_val_if_fail(self == NULL, -1);
923
924         custom_set_data(self, data);
925         return 0;
926 }
927
928 /**
929         Read the customdata from an OBEX handle.
930         \param self OBEX handle
931         \return custom transport data, NULL on error
932  */
933 LIB_SYMBOL
934 void * CALLAPI OBEX_GetCustomData(obex_t *self)
935 {
936         obex_return_val_if_fail(self == NULL, NULL);
937
938         return custom_get_data(self);
939 }
940
941 /**
942         Start listening for incoming TCP connections.
943         \param self OBEX handle
944         \param addr Address to bind to (*:650 if NULL)
945         \param addrlen Length of address structure
946         \return -1 on error
947
948         An easier server function to use for TCP/IP (TcpOBEX) only.
949         It supports IPv4 (AF_INET) and IPv6 (AF_INET6).
950         Note: INADDR_ANY will get mapped to IN6ADDR_ANY and using port 0
951         will select the default OBEX port.
952  */
953 LIB_SYMBOL
954 int CALLAPI TcpOBEX_ServerRegister(obex_t *self, struct sockaddr *addr,
955                                                                 int addrlen)
956 {
957         DEBUG(3, "\n");
958
959         errno = EINVAL;
960         obex_return_val_if_fail(self != NULL, -1);
961
962         inobex_prepare_listen(self, addr, addrlen);
963
964         return obex_transport_listen(self)? 1: -1;
965 }
966
967 /**
968         Connect TCP transport.
969         \param self OBEX handle
970         \param addr Address to connect to ([::1]:650 if NULL)
971         \param addrlen Length of address structure
972         \return -1 on error
973
974         An easier connect function to use for TCP/IP (TcpOBEX) only.
975         It supports IPv4 (AF_INET) and IPv6 (AF_INET6).
976  */
977 LIB_SYMBOL
978 int CALLAPI TcpOBEX_TransportConnect(obex_t *self, struct sockaddr *addr,
979                                                                 int addrlen)
980 {
981         DEBUG(4, "\n");
982
983         errno = EINVAL;
984         obex_return_val_if_fail(self != NULL, -1);
985
986         if (self->object) {
987                 DEBUG(1, "We are busy.\n");
988                 errno = EBUSY;
989                 return -1;
990         }
991
992         inobex_prepare_connect(self, addr, addrlen);
993
994         return obex_transport_connect_request(self)? 1: -1;
995 }
996
997 /**
998         Start listening for incoming connections.
999         \param self OBEX handle
1000         \param service Service to bind to.
1001         \return -1 or negative error code on error
1002
1003         An easier server function to use for IrDA (IrOBEX) only.
1004  */
1005 LIB_SYMBOL
1006 int CALLAPI IrOBEX_ServerRegister(obex_t *self, const char *service)
1007 {
1008         DEBUG(3, "\n");
1009
1010         obex_return_val_if_fail(self != NULL, -1);
1011         obex_return_val_if_fail(service != NULL, -1);
1012
1013 #ifdef HAVE_IRDA
1014         irobex_prepare_listen(self, service);
1015         return obex_transport_listen(self)? 1: -1;
1016 #else
1017         return -ESOCKTNOSUPPORT;
1018 #endif /* HAVE_IRDA */
1019 }
1020
1021 /**
1022         Connect Irda transport.
1023         \param self OBEX handle
1024         \param service IrIAS service name to connect to
1025         \return -1 or negative error code on error
1026
1027         An easier connect function to use for IrDA (IrOBEX) only.
1028  */
1029 LIB_SYMBOL
1030 int CALLAPI IrOBEX_TransportConnect(obex_t *self, const char *service)
1031 {
1032         obex_interface_t *intf;
1033         int err;
1034
1035         DEBUG(4, "\n");
1036
1037         err = OBEX_EnumerateInterfaces(self);
1038         if (err <= 0)
1039                 return -1;
1040
1041         intf = OBEX_GetInterfaceByIndex(self, 0);
1042         intf->irda.service = service;
1043
1044         return OBEX_InterfaceConnect(self, intf);
1045 }
1046
1047 /**
1048         Start listening for incoming connections.
1049         \param self OBEX handle
1050         \param src source address to listen on
1051         \param channel source channel to listen on
1052         \return -1 or negative error code on error
1053
1054         An easier server function to use for Bluetooth (Bluetooth OBEX) only.
1055  */
1056 LIB_SYMBOL
1057 int CALLAPI BtOBEX_ServerRegister(obex_t *self, const bt_addr_t *src, uint8_t channel)
1058 {
1059         DEBUG(3, "\n");
1060
1061         obex_return_val_if_fail(self != NULL, -1);
1062
1063 #ifdef HAVE_BLUETOOTH
1064         if (src == NULL)
1065                 src = BDADDR_ANY;
1066         btobex_prepare_listen(self, src, channel);
1067         return obex_transport_listen(self)? 1: -1;
1068 #else
1069         return -ESOCKTNOSUPPORT;
1070 #endif /* HAVE_BLUETOOTH */
1071 }
1072
1073 /**
1074         Connect Bluetooth transport.
1075         \param self OBEX handle
1076         \param src source address to connect from
1077         \param dst destination address to connect to
1078         \param channel destination channel to connect to
1079         \return -1 or negative error code on error
1080
1081         An easier connect function to use for Bluetooth (Bluetooth OBEX) only.
1082  */
1083 LIB_SYMBOL
1084 int CALLAPI BtOBEX_TransportConnect(obex_t *self, const bt_addr_t *src,
1085                                         const bt_addr_t *dst, uint8_t channel)
1086 {
1087         DEBUG(4, "\n");
1088
1089         obex_return_val_if_fail(self != NULL, -1);
1090
1091         if (self->object) {
1092                 DEBUG(1, "We are busy.\n");
1093                 return -EBUSY;
1094         }
1095
1096         obex_return_val_if_fail(dst != NULL, -1);
1097
1098 #ifdef HAVE_BLUETOOTH
1099         if (src == NULL)
1100                 src = BDADDR_ANY;
1101         btobex_prepare_connect(self, src, dst, channel);
1102         return obex_transport_connect_request(self)? 1: -1;
1103 #else
1104         return -ESOCKTNOSUPPORT;
1105 #endif /* HAVE_BLUETOOTH */
1106 }
1107
1108 /*
1109         FdOBEX_TransportSetup - setup descriptors for OBEX_TRANS_FD transport.
1110
1111         \param self OBEX handle
1112         \param rfd descriptor to read
1113         \param wfd descriptor to write
1114         \param mtu (ignored)
1115         \return -1 or negative error code on error
1116  */
1117 LIB_SYMBOL
1118 int CALLAPI FdOBEX_TransportSetup(obex_t *self, int rfd, int wfd, int mtu)
1119 {
1120         DEBUG(4, "\n");
1121
1122         obex_return_val_if_fail(self != NULL, -1);
1123
1124         if (self->object) {
1125                 DEBUG(1, "We are busy.\n");
1126                 return -EBUSY;
1127         }
1128         fdobex_set_fd(self, rfd, wfd);
1129         return obex_transport_connect_request(self)? 1: -1;
1130 }
1131
1132 /**
1133         Connect USB interface.
1134         \param self OBEX handle
1135         \param intf USB interface to connect to
1136         \return -1 or negative error code on error
1137
1138         An easier connect function to connect to a discovered interface
1139         (currently USB OBEX only).
1140  */
1141 LIB_SYMBOL
1142 int CALLAPI OBEX_InterfaceConnect(obex_t *self, obex_interface_t *intf)
1143 {
1144         DEBUG(4, "\n");
1145
1146         obex_return_val_if_fail(self != NULL, -1);
1147
1148         if (self->object) {
1149                 DEBUG(1, "We are busy.\n");
1150                 return -EBUSY;
1151         }
1152
1153         obex_return_val_if_fail(intf != NULL, -1);
1154         if (self->trans->ops->client.select_interface) {
1155                 if (!self->trans->ops->client.select_interface(self, intf))
1156                         return -1;
1157                 return obex_transport_connect_request(self)? 1: -1;
1158         } else
1159                 return -ESOCKTNOSUPPORT;
1160 }
1161
1162 /**
1163         Find OBEX interfaces on the system.
1164         \param self OBEX handle
1165         \return the number of OBEX interfaces.
1166  */
1167 LIB_SYMBOL
1168 int CALLAPI OBEX_EnumerateInterfaces(obex_t *self)
1169 {
1170         DEBUG(4, "\n");
1171
1172         obex_return_val_if_fail(self != NULL, -1);
1173
1174         OBEX_FreeInterfaces(self);
1175         obex_transport_enumerate(self);
1176
1177         return self->interfaces_number;
1178 }
1179
1180 /**
1181         Get OBEX interface information.
1182         \param self OBEX handle
1183         \param i interface number
1184         \return OBEX interface information.
1185  */
1186 LIB_SYMBOL
1187 obex_interface_t * CALLAPI OBEX_GetInterfaceByIndex(obex_t *self, int i)
1188 {
1189         DEBUG(4, "\n");
1190
1191         obex_return_val_if_fail(self != NULL, NULL);
1192
1193         if (i >= self->interfaces_number || i < 0)
1194                 return NULL;
1195         return &self->interfaces[i];
1196 }
1197
1198 /**
1199         Free memory allocated to OBEX interface structures.
1200         \param self OBEX handle
1201
1202         Frees memory allocated to OBEX interface structures after it has been
1203         allocated by OBEX_EnumerateInterfaces.
1204  */
1205 LIB_SYMBOL
1206 void CALLAPI OBEX_FreeInterfaces(obex_t *self)
1207 {
1208         obex_return_if_fail(self != NULL);
1209
1210         obex_transport_free_interfaces(self);
1211 }