1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
24 #ifndef __OBEXSERVER_H
25 #define __OBEXSERVER_H
27 #include <obextypes.h>
28 #include <obex/internal/obextransportconstants.h>
31 class TObexTransportInfo;
32 class CObexServerRequestPacketEngine;
33 class CObexPacketSignaller;
34 class MObexReadActivityObserver;
38 CObexServer provides a framework for servicing OBEX requests from remote clients.
39 It is designed to be able to act as either a "default" application (in IrDA
40 terms, registering on the IrDA:OBEX IAS class), or as a application specific
41 server (registering itself on a private IAS class).
43 You implement service-specific behaviour by providing a MObexServerNotify
44 interface implementation to the server object. The server calls the interface's
45 functions to provide notification of server events, which specific implementations
46 can process (or ignore) as appropriate.
48 This class is not designed for user derivation.
53 NONSHARABLE_CLASS(CObexServer) : public CObex
55 // CObexServer is friends with the core Server State Machine class so
56 // that it can access the CObex::ControlledTransportDown() method
57 friend class CObexServerStateMachine;
59 // CObexServer is friends with the TObexServerStateObexConnecting class so
60 // that it can access the CObex::SetConnectState(TConnectState aNewState) method
61 friend class TObexServerStateObexConnecting;
63 // CObexServer is friends with the Server Request Packet Engine so that
64 // it can NULL the iServerRequestPacketEngine pointer ready for another
65 // extension interface
66 friend class CObexServerRequestPacketEngine;
73 The target header checking to apply to incoming connection requests. Defaults to
75 @see CObexServer::SetTargetChecking
79 ENoChecking, /** Allow all target headers to connect. */
80 EIfPresent, /** Only check target header in response to receiving one. Allows all clients
81 specifying an Inbox service to connect. */
82 EAlways, /** Strict checking. Only allow connections if target header matches or no header
83 received and none expected. */
86 IMPORT_C static CObexServer* NewL(TObexProtocolInfo& aObexProtocolInfoPtr);
87 IMPORT_C static CObexServer* NewL(TObexProtocolInfo& aObexProtocolInfoPtr, TObexProtocolPolicy& aObexProtocolPolicy);
88 IMPORT_C static CObexServer* NewL(TObexTransportInfo& aObexTransportInfo);
89 IMPORT_C ~CObexServer();
90 IMPORT_C TInt Start(MObexServerNotify* aOwner);
91 IMPORT_C TInt Start(MObexServerNotifyAsync* aOwner);
93 IMPORT_C TBool IsStarted();
94 IMPORT_C TOperation CurrentOperation() const;
95 void SetCurrentOperation(const TOperation aOperation); // used internally by state machine
96 IMPORT_C void SetChallengeL(const TDesC& aPassword);
97 IMPORT_C void ResetChallenge();
98 IMPORT_C void UserPasswordL( const TDesC& aPassword);
99 IMPORT_C void SetTargetChecking(TTargetChecking aChecking);
100 IMPORT_C TInt SetPutFinalResponseHeaders(CObexHeaderSet* aHeaderSet);
101 IMPORT_C TInt RequestIndicationCallback(CObexBaseObject* aObject);
102 IMPORT_C TInt RequestIndicationCallbackWithError(TObexResponse aResponseCode);
103 IMPORT_C TInt RequestIndicationCallbackWithError(TInt aErrorCode);
104 IMPORT_C TInt RequestCompleteIndicationCallback(TObexResponse aResponseCode);
105 IMPORT_C TInt RequestCompleteIndicationCallback(TInt aErrorCode);
107 IMPORT_C TInt PacketHeaders(CObexHeaderSet*& aHeaderSet);
108 IMPORT_C TInt PacketHeaders(CObexHeaderSet*& aHeaderSet, MObexHeaderCheck& aHeaderCheck);
109 IMPORT_C void SetReadActivityObserver(MObexReadActivityObserver* aObserver);
110 // @internalTechnology
111 IMPORT_C TAny* ExtensionInterfaceL(TUid aUid);
112 IMPORT_C const TObexTransportInfo* TransportInfo() const;
115 // Called from CObexNotifyExtendServer
116 void SignalPacketProcessEvent(TObexPacketProcessEvent aEvent);
118 // Unexported functions used by the Server state machine
119 TBool CheckObjectForConnectionId(CObexBaseObject& aObject);
120 TBool CheckPacketForConnectionId(CObexPacket& aObject);
124 void ConstructL(TObexTransportInfo& aObexTransportInfo);
125 TInt AcceptConnection();
126 // Implementation of CObex Events
127 virtual void OnPacketReceive(CObexPacket& aPacket);
128 virtual void OnError(TInt aError);
129 virtual void OnTransportUp();
130 virtual void OnTransportDown();
133 // These three functions need to be public so the Server state machine can use them
134 // However ParseConnectPacket cannot be moved as it is a virtual function (from CObex)
135 TInt PrepareConnectPacket(CObexPacket& aPacket);
136 TInt PrepareErroredConnectPacket(CObexPacket& aPacket);
137 void SignalReadActivity();
138 TInt ParseConnectPacket(CObexPacket& aPacket);
141 TInt AddConnectionIDHeader(CObexPacket& aPacket);
142 TInt PrepareFinalChallResponse(CObexPacket& aPacket, TConnectState& aNextState);
143 void CheckTarget(TConnectState& aNextState, TInt& aRetVal);
144 void ResetConnectionID();
145 void SetConnectionID(TUint32 aConnectionID);
146 TUint32 ConnectionID();
147 void CheckServerAppResponseCode(TObexOpcode aOpcode, TObexResponse aResponse);
148 TInt DoPacketHeaders(CObexHeaderSet*& aHeaderSet, MObexHeaderCheck* aHeaderCheck);
151 MObexServerNotifyAsync* iOwner;
154 TBool iTargetReceived;
155 TTargetChecking iTargetChecking;
156 TUint32 iConnectionID;
157 TBool iConnectionIdSet;
158 CObexHeader* iHeader;
159 CObexServerStateMachine* iStateMachine;
160 CObexServerNotifySyncWrapper* iSyncWrapper;
161 CObexServerRequestPacketEngine* iServerRequestPacketEngine;
162 CObexPacketSignaller* iPacketProcessSignaller;
166 /** OBEX synchronous server notification interface.
168 Any service that provides OBEX server functionality must implement one of the two
169 server observer classes -- this one or MObexServerNotifyAsync.
171 The CObexServer object handles the protocol side of an OBEX server session,
172 while this class provides the server policy for a particular session.
174 PUT and GET requests are handled synchronously, with the implementer returning a
175 CObexBufObject which will be processed immediately.
179 @see MObexServerNotifyAsync
182 class MObexServerNotify
186 Returns a null aObject if the extension is not implemented, or a pointer to another interface if it is.
187 @param aInterface UID of the interface to return
188 @param aObject the container for another interface as specified by aInterface
190 IMPORT_C virtual void MOSN_ExtensionInterfaceL(TUid aInterface, void*& aObject);
192 /** Called if an OBEX protocol error occurs.
194 It is only called for fatal errors that cause the OBEX connection to terminate.
195 An error that does not terminate the connection, for example the server issuing
196 a semantically valid, but unrecognised command, will not be indicated.
198 @param aError Error code that describes the OBEX error. OBEX specific error
199 codes are listed from KErrIrObexClientNoDevicesFound.
204 virtual void ErrorIndication(TInt aError) =0;
208 /** Called when the underlying transport connection is made from a remote
209 client to the server.
211 Note that this does not, however, indicate an OBEX connection has been successfully
214 You can define any low-level connection policy here. It is also a good place
215 to set up the local connection information (CObex::LocalInfo()), if any non-defaults
221 virtual void TransportUpIndication() =0;
225 /** Called when the transport connection is dropped (by either party).
227 It is called whether the OBEX connection was gracefully disconnected or not.
228 The function is the definitive place for disconnection processing.
233 virtual void TransportDownIndication() =0;
237 /** Called when an OBEX connection is made from a remote client.
239 Override this function to provide any extra OBEX connection processing.
240 Despite this method returning a value, implementers cannot use this to
241 refuse the connection attempt.
243 @param aRemoteInfo Connection information supplied by that remote machine
244 @param aInfo Further information about the requested connection (reserved)
250 virtual TInt ObexConnectIndication(const TObexConnectInfo& aRemoteInfo, const TDesC8& aInfo) =0;
254 /** Called on a (graceful) OBEX disconnection by the client.
256 Override this to provide any extra processing OBEX disconnection processing.
258 Note that this indication will not be raised if the remote machine simply
259 drops the transport connection. However, ErrorIndication() will be called
260 if the disconnection is unexpected/ invalid (i.e. another operation was in
261 progress at the time). In all cases, TransportDownIndication() will be called.
263 @param aInfo Contains information about the disconnection (reserved)
268 virtual void ObexDisconnectIndication(const TDesC8& aInfo) =0;
272 /** Called on receipt of the first packet of a (valid) put request.
274 It is called before any parsing of the packet is performed, simply to establish
275 whether this server is interested in receiving objects at all.
277 Note if the returned object cannot be initialised for receiving, ERespInternalError
278 is returned to the client.
280 @return CObexBaseObject-derived object, which the object being put will be
281 parsed into. If this is NULL, ERespForbidden is returned to the client.
286 virtual CObexBufObject* PutRequestIndication() =0;
290 /** Called on receipt of every packet of an OBEX PUT operation.
292 It will always be preceded by a PutRequestIndication(). The object returned
293 by the request indication will be updated to reflect all the information received
294 concerning the object which the client is sending, from packets up to and
295 including the current one.
297 You can use this function to provide periodic user notification on the progress
298 of the transfer (noting that the Length attribute may take an arbitrary number
299 of packets to become non-zero, and the constraints on its accuracy). Due to
300 the nature of OBEX operations, where any header attribute can be sent at any
301 point in the transfer, this is also a good place to marshal the details of
302 a received object, and possibly prompt for action on the received object (e.g.
303 renaming on filename clashes).
305 Note that this function could be hit quite heavily, in proportion to the size
306 of the object transferred. Therefore more consideration should be given to
307 the speed of execution of this function than that of the other indications.
309 @return KErrNone instructs the server to allow the client to continue the put
310 operation. Any other value cancels the operation with an appropriate OBEX
311 server response code.
316 virtual TInt PutPacketIndication() =0;
320 /** Called after the final put packet has been successfully received and parsed.
322 Note that there will not necessarily be a call to this function corresponding
323 to each PutRequestIndication() as, if an error occurs while the put is being
324 carried out, ErrorIndication() will be called instead.
326 Before version 6.1, the return type was void.
328 @return KErrNoneinstructs the remote client that the put completed successfully.
329 Any other value cancels the operation with an appropriate OBEX server response
335 virtual TInt PutCompleteIndication() =0;
339 /** Called when a full get request has been received from the client.
341 aRequestedObject holds all the details about the object the remote client
342 has requested. Use this function to analyse the client's request, and return
343 a pointer to the object to be returned to the client, or NULL to return no
346 If NULL is returned, the server will send ERespForbidden to the client; if
347 an error occurs in returning the object, ERespInternalError is returned, otherwise
348 the returned object is sent back to the client.
350 @param aRequiredObject Details about the object the remote client has requested
351 @return Object to return to the client
356 virtual CObexBufObject* GetRequestIndication(CObexBaseObject *aRequiredObject) =0;
360 /** Called for every packet of get reply sent by the server back to the client.
362 The function is only called while an object is being sent to the client, not
363 while the client is providing its initial specification for the object it
366 You can use this function to provide user notification on the object being
367 sent, and its progress. As with PutPacketIndication(), you should consider
368 that this function might get called often, especially for large objects and
369 small OBEX packet sizes, so the speed of execution here is important.
371 @return KErrNone to continue sending the object, or any other error code to
377 virtual TInt GetPacketIndication() =0;
381 /** Called when the final packet of the object has been returned to the client.
383 Note like PutCompleteIndication(), this function might not be called for each
384 GetRequestIndication(), if the operation is interrupted by an error.
386 Before version 6.1, the return type was void.
388 @return KErrNoneinstructs the remote client that the get completed successfully.
389 Any other value cancels the operation with an appropriate OBEX server response
395 virtual TInt GetCompleteIndication() =0;
399 /** Called when an OBEX SETPATH command is received by the server.
401 @param aPathInfo SETPATH command parameters
402 @param aInfo Not currently used
403 @return System wide error code indicating the success of the setpath command
408 virtual TInt SetPathIndication(const CObex::TSetPathInfo& aPathInfo, const TDesC8& aInfo) =0;
412 /** Called when an abort packet is received from the client.
414 An OBEX abort command simply cancels the current operation, and does not necessarily
415 have to cause the connection to be dropped. On return, a ERespSuccess packet
416 is sent to the client.
421 virtual void AbortIndication() =0;
426 /** OBEX asynchronous server notification interface.
428 Any service that provides OBEX server functionality must implement one of the two
429 server observer classes -- this one or MObexServerNotify.
431 The CObexServer object handles the protocol side of an OBEX server session,
432 while this class provides the server policy for a particular session.
434 PUT and GET requests are handled asynchronously, with the upcall from the server
435 being followed at some stage in the future by a call to CObexServer::RequestIndicationComplete
436 to trigger processing.
440 @see MObexServerNotify
443 class MObexServerNotifyAsync
448 Returns a null aObject if the extension is not implemented, or a pointer to another
450 @param aInterface UID of the interface to return
451 @param aObject the container for another interface as specified by aInterface
453 IMPORT_C virtual void MOSNA_ExtensionInterfaceL(TUid aInterface, void*& aObject);
457 /** Called if an OBEX protocol error occurs.
459 It is only called for fatal errors that cause the OBEX connection to terminate.
460 An error that does not terminate the connection, for example the server issuing
461 a semantically valid, but unrecognised command, will not be indicated.
463 @param aError Error code that describes the OBEX error. OBEX specific error
464 codes are listed from KErrIrObexClientNoDevicesFound.
469 virtual void ErrorIndication(TInt aError) =0;
473 /** Called when the underlying transport connection is made from a remote
474 client to the server.
476 Note that this does not, however, indicate an OBEX connection has been successfully
479 You can define any low-level connection policy here. It is also a good place
480 to set up the local connection information (CObex::LocalInfo()), if any non-defaults
486 virtual void TransportUpIndication() =0;
490 /** Called when the transport connection is dropped (by either party).
492 It is called whether the OBEX connection was gracefully disconnected or not.
493 The function is the definitive place for disconnection processing.
498 virtual void TransportDownIndication() =0;
502 /** Called when an OBEX connection is made from a remote client.
504 Override this function to provide any extra OBEX connection processing.
506 @param aRemoteInfo Connection information supplied by that remote machine
507 @param aInfo Further information about the requested connection (reserved)
512 virtual void ObexConnectIndication(const TObexConnectInfo& aRemoteInfo, const TDesC8& aInfo) =0;
516 /** Called on a (graceful) OBEX disconnection by the client.
518 Override this to provide any extra processing OBEX disconnection processing.
520 Note that this indication will not be raised if the remote machine simply
521 drops the transport connection. However, ErrorIndication() will be called
522 if the disconnection is unexpected/ invalid (i.e. another operation was in
523 progress at the time). In all cases, TransportDownIndication() will be called.
525 @param aInfo Contains information about the disconnection (reserved)
530 virtual void ObexDisconnectIndication(const TDesC8& aInfo) =0;
534 /** Called on receipt of the first packet of a (valid) put request.
536 It is called before any parsing of the packet is performed, simply to establish
537 whether this server is interested in receiving objects at all.
539 Following this notification, the server will wait for a call to
540 CObexServer::RequestIndicationCallback supplying a CObexBaseObject derived
541 object to receive into or a response code specifying the error.
546 virtual void PutRequestIndication() =0;
550 /** Called on receipt of every packet of an OBEX PUT operation.
552 It will always be preceded by a PutRequestIndication(). The object returned
553 by the request indication will be updated to reflect all the information received
554 concerning the object which the client is sending, from packets up to and
555 including the current one.
557 You can use this function to provide periodic user notification on the progress
558 of the transfer (noting that the Length attribute may take an arbitrary number
559 of packets to become non-zero, and the constraints on its accuracy). Due to
560 the nature of OBEX operations, where any header attribute can be sent at any
561 point in the transfer, this is also a good place to marshal the details of
562 a received object, and possibly prompt for action on the received object (e.g.
563 renaming on filename clashes).
565 Note that this function could be hit quite heavily, in proportion to the size
566 of the object transferred. Therefore more consideration should be given to
567 the speed of execution of this function than that of the other indications.
569 @return KErrNone instructs the server to allow the client to continue the put
570 operation. Any other value cancels the operation with an appropriate OBEX
571 server response code.
576 virtual TInt PutPacketIndication() =0;
580 /** Called after the final put packet has been successfully received and parsed.
582 Note that there will not necessarily be a call to this function corresponding
583 to each PutRequestIndication() as, if an error occurs while the put is being
584 carried out, ErrorIndication() will be called instead.
586 Following this notification, the server will wait for a call to
587 CObexServer::RequestCompleteIndicationCallback supplying a Obex response code.
592 virtual void PutCompleteIndication() =0;
596 /** Called when a full get request has been received from the client.
598 aRequestedObject holds all the details about the object the remote client
599 has requested. Use this function to analyse the client's request, and return
600 a pointer to the object to be returned to the client, or NULL to return no
603 Following this notification, the server will wait for a call to
604 CObexServer::RequestIndicationCallback supplying a CObexBaseObject derived
605 object to send to the client or a response code specifying the error.
607 @param aRequiredObject Details about the object the remote client has requested
612 virtual void GetRequestIndication(CObexBaseObject* aRequiredObject) =0;
616 /** Called for every packet of get reply sent by the server back to the client.
618 The function is only called while an object is being sent to the client, not
619 while the client is providing its initial specification for the object it
622 You can use this function to provide user notification on the object being
623 sent, and its progress. As with PutPacketIndication(), you should consider
624 that this function might get called often, especially for large objects and
625 small OBEX packet sizes, so the speed of execution here is important.
627 @return KErrNone to continue sending the object, or any other error code to
633 virtual TInt GetPacketIndication() =0;
637 /** Called when the final packet of the object has been returned to the client.
639 Note like PutCompleteIndication(), this function might not be called for each
640 GetRequestIndication(), if the operation is interrupted by an error.
642 Following this notification, the server will wait for a call to
643 CObexServer::RequestCompleteIndicationCallback supplying a Obex response code.
648 virtual void GetCompleteIndication() =0;
652 /** Called when an OBEX SETPATH command is received by the server.
654 Following this notification, the server will wait for a call to
655 CObexServer::RequestCompleteIndicationCallback supplying a Obex response code.
657 @param aPathInfo SETPATH command parameters
658 @param aInfo Not currently used
663 virtual void SetPathIndication(const CObex::TSetPathInfo& aPathInfo, const TDesC8& aInfo) =0;
667 /** Called when an abort packet is received from the client.
669 An OBEX abort command simply cancels the current operation, and does not necessarily
670 have to cause the connection to be dropped. On return, a ERespSuccess packet
671 is sent to the client.
676 virtual void AbortIndication() =0;
680 /** Cancel an asynchronous callback request (ie. PutRequest/GetRequest/PutComplete/GetComplete/SetPath
683 Note that ignoring this call will lead to a panic when the indication callback function
689 virtual void CancelIndicationCallback() =0;
693 #endif // __OBEXSERVER_H