3 /// Virtual parser wrapper
7 Copyright (C) 2005-2010, Net Direct Inc. (http://www.netdirect.ca/)
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
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.
18 See the GNU General Public License in the COPYING file at the
19 root directory of this project for more details.
22 #ifndef __BARRY_PARSER_H__
23 #define __BARRY_PARSER_H__
28 #include <stdint.h> // for uint32_t
32 // forward declarations
52 // This macro can be used to automatically generate code for all known
53 // record types. Just #undef HANDLE_PARSER, then #define it to whatever
54 // you need, then use ALL_KNOWN_PARSER_TYPES. See parser.cc for
57 // These are sorted so their GetDBName()'s will display in alphabetical order.
59 #define ALL_KNOWN_PARSER_TYPES \
60 HANDLE_PARSER(Contact) \
61 HANDLE_PARSER(Bookmark) \
62 HANDLE_PARSER(Calendar) \
63 HANDLE_PARSER(CalendarAll) \
64 HANDLE_PARSER(Folder) \
66 HANDLE_PARSER(Message) \
67 HANDLE_PARSER(CallLog) \
68 HANDLE_PARSER(PINMessage) \
69 HANDLE_PARSER(SavedMessage) \
70 HANDLE_PARSER(ServiceBook) \
73 HANDLE_PARSER(Timezone)
80 /// Base class for the parser hierarchy.
82 /// This class provides the interface that the Controller class uses
83 /// to pass raw data it reads from the device. The Controller, along
84 /// with the Packet class, calls each of the virtual functions below
85 /// in the same order.
87 /// This class is kept as a pure abstract class, in order to make sure
88 /// that the compiler will catch any API changes, for code derived
97 /// Called to parse sub fields in the raw data packet.
98 virtual void ParseRecord(const DBData
&data
, const IConverter
*ic
) = 0;
105 /// If in debug mode, this class can be used as a null parser.
106 /// Call Init() and the protocol will be dumped to stdout and
107 /// no parsing will be done.
109 /// Do NOT derive your own personal parser classes from this,
110 /// unless you are perfectly confident that you will catch
111 /// future API changes on the devel tree without the compiler's
114 class BXEXPORT NullParser
: public Parser
118 virtual ~NullParser() {}
120 virtual void ParseRecord(const DBData
&data
, const IConverter
*ic
) {}
126 /// Dumps raw hex of the given DBData to the given stream.
128 /// Do NOT derive your own personal parser classes from this,
129 /// unless you are perfectly confident that you will catch
130 /// future API changes on the devel tree without the compiler's
133 class BXEXPORT HexDumpParser
: public Parser
138 explicit HexDumpParser(std::ostream
&os
);
140 virtual void ParseRecord(const Barry::DBData
&data
,
141 const IConverter
*ic
);
147 /// Abstract base class for the following RecordParser template, that exposes
148 /// some information on the specifics that the record parser can handle.
149 /// Specifically, it exposes the database name it is able to parse
151 class BXEXPORT RecordParserBase
: public Parser
154 // These functions are always valid, regardless of the
155 // state of the parser.
156 virtual const char * GetDBName() const = 0;
157 virtual uint8_t GetDefaultRecType() const = 0;
159 // These functions depend on the parser having just parsed
160 // a record successfully.
161 virtual bool IsRecordValid() const = 0;
162 virtual uint8_t GetRecType() const = 0;
163 virtual uint32_t GetUniqueId() const = 0;
164 virtual void Dump(std::ostream
&os
) const = 0;
169 // Note: Store classes take parsed Record objects as a functor.
170 // Parser classes deal with raw data, while Store classes deal with
171 // parsed Record objects.
177 /// A Storage class for RecordParser<> that does nothing, for the cases
178 /// where you only want to dump parsed record data to a stream.
180 template <class RecordT
>
184 void operator() (const RecordT
&r
)
192 /// A Storage class for RecordParser<> that dumps the parsed record data
193 /// to the given stream.
195 template <class RecordT
>
201 explicit DumpStore(std::ostream
&os
)
206 void operator() (const RecordT
&r
)
213 // RecordParser template class
215 /// Template class for easy creation of specific parser objects. This template
216 /// takes the following template arguments:
218 /// - RecordT: One of the record parser classes in record.h
219 /// - StorageT: A custom storage functor class. An object of this type
220 /// will be called as a function with parsed Record as an
221 /// argument. This happens on the fly as the data is retrieved
222 /// from the device over USB, so it should not block forever.
224 /// Example LoadDatabase() call:
227 /// struct StoreContact
229 /// std::vector<Contact> &array;
230 /// StoreContact(std::vector<Contact> &a) : array(a) {}
231 /// void operator() (const Contact &c)
233 /// array.push_back(c);
237 /// Controller con(probeResult);
238 /// con.OpenMode(Controller::Desktop);
239 /// std::vector<Contact> contactList;
240 /// StoreContact storage(contactList);
241 /// RecordParser<Contact, StoreContact> parser(storage);
242 /// con.LoadDatabase(con.GetDBID("Address Book"), parser);
245 template <class RecordT
, class StorageT
>
246 class RecordParser
: public RecordParserBase
254 /// Constructor that references an externally managed storage object.
255 RecordParser(StorageT
&storage
)
258 , m_record_valid(false)
262 /// Constructor that references a locally managed storage object.
263 /// The pointer passed in will be stored, and freed when this class
264 /// is destroyed. It is safe to call this constructor with
265 /// a 'new'ly created storage object.
266 RecordParser(StorageT
*storage
= 0)
269 , m_record_valid(false)
279 virtual StorageT
* GetStore()
284 virtual const StorageT
* GetStore() const
289 virtual void ParseRecord(const DBData
&data
, const IConverter
*ic
)
292 m_record_valid
= false;
294 m_rec
.SetIds(data
.GetRecType(), data
.GetUniqueId());
295 size_t offset
= data
.GetOffset();
296 m_rec
.ParseHeader(data
.GetData(), offset
);
297 m_rec
.ParseFields(data
.GetData(), offset
, ic
);
298 m_record_valid
= true;
305 // RecordParserBase overrides
308 // These functions are always valid, regardless of the
309 // state of the parser.
310 virtual const char * GetDBName() const
312 return RecordT::GetDBName();
315 virtual uint8_t GetDefaultRecType() const
317 return RecordT::GetDefaultRecType();
320 // These functions depend on the parser having just parsed
321 // a record successfully.
322 virtual bool IsRecordValid() const
324 return m_record_valid
;
327 virtual uint8_t GetRecType() const
329 return m_rec
.GetRecType();
332 virtual uint32_t GetUniqueId() const
334 return m_rec
.GetUniqueId();
337 virtual void Dump(std::ostream
&os
) const
346 /// Base class with overloaded functor behaviour for all available
347 /// record classes. To be used with AllRecordParser.
349 class BXEXPORT AllRecordStore
353 virtual ~AllRecordStore() {}
356 #define HANDLE_PARSER(tname) \
357 virtual void operator() (const Barry::tname &) = 0;
359 ALL_KNOWN_PARSER_TYPES
365 /// Container parser class that accepts multiple Parser objects
366 /// (often RecordParser<> objects but they don't have to be) and
367 /// automatically routes incoming records to the appropriate parser.
368 /// Note that this container owns *all* Parser objects, and will
369 /// free them upon destruction.
371 /// Incoming records that have no matching parser are passed to the
372 /// default parser object, if one exists, otherwise they are dropped
373 /// silently. The default parser object is also owned by the container,
374 /// and will be freed on destruction.
376 /// Do NOT derive your own personal parser classes from this,
377 /// unless you are perfectly confident that you will catch
378 /// future API changes on the devel tree without the compiler's
381 class BXEXPORT MultiRecordParser
: public Parser
383 typedef std::map
<std::string
, Parser
*> map_type
;
389 // takes ownership of default_parser!
390 explicit MultiRecordParser(Parser
*default_parser
= 0);
391 ~MultiRecordParser();
393 /// Adds given parser to list and takes ownership of it
394 void Add(const std::string
&dbname
, Parser
*parser
);
396 /// Adds given parser to list and takes ownership of it
397 void Add(RecordParserBase
*parser
);
399 /// Creates a RecordParser<> object using the given record
400 /// type and AllRecordStore. Does NOT take ownership of the
401 /// store object, since it can be used multiple times for
402 /// multiple records.
403 template <class RecordT
>
404 void Add(AllRecordStore
&store
)
406 Add( RecordT::GetDBName(),
407 new RecordParser
<RecordT
, AllRecordStore
>(store
) );
410 /// Two helper template functions that create the RecordParser<>
411 /// automatically based on the function call. Both pointer and
412 /// reference versions.
413 template <class RecordT
, class StorageT
>
414 void Add(StorageT
*store
)
416 Add( RecordT::GetDBName(),
417 new RecordParser
<RecordT
, StorageT
>(store
) );
420 template <class RecordT
, class StorageT
>
421 void Add(StorageT
&store
)
423 Add( RecordT::GetDBName(),
424 new RecordParser
<RecordT
, StorageT
>(store
) );
427 /// Creates a RecordParser<> object for the given database name,
428 /// using DumpStore<> with the given stream for the output,
429 /// and adds it to list.
430 /// Returns false if there is no known Record class for dbname.
431 bool Add(const std::string
&dbname
, std::ostream
&os
);
433 /// Creates a RecordParser<> object for the given database name,
434 /// using the given store object.
435 /// Returns false if there is no known Record class for dbname.
436 bool Add(const std::string
&dbname
, AllRecordStore
&store
);
439 virtual void ParseRecord(const DBData
&data
, const IConverter
*ic
);
443 // AllRecordDumpStore
445 /// Derived from AllRecordStore, which just calls each record's
446 /// Dump() member with the given stream.
448 class BXEXPORT AllRecordDumpStore
: public AllRecordStore
454 explicit AllRecordDumpStore(std::ostream
&os
)
460 #define HANDLE_PARSER(tname) \
461 virtual void operator() (const Barry::tname &);
463 ALL_KNOWN_PARSER_TYPES
469 /// Convenience parser that creates a MultiRecordParser with all known
470 /// record parsers added. If an AllRecordStore pointer is passed in,
471 /// this class takes ownership of it, and uses it as the store object
472 /// for all the RecordParser<> objects it creates. If not, then
473 /// a custom DumpStore<> object is created with the given stream
474 /// for each RecordParser<> added.
476 /// The default parser object behaves just like MultiRecordParser
478 /// This class takes ownership of all pointers passed in.
480 class BXEXPORT AllRecordParser
: public MultiRecordParser
482 AllRecordStore
*m_store
;
485 // takes ownership of default_parser and store!
486 explicit AllRecordParser(std::ostream
&os
,
487 Parser
*default_parser
= 0,
488 AllRecordStore
*store
= 0);
495 /// Sends incoming DBData objects to all the parsers in its list.
496 /// This parser container does NOT own the parsers added.
498 class BXEXPORT TeeParser
: public Parser
500 typedef std::vector
<Parser
*> parser_list_type
;
502 parser_list_type m_external_parsers
, m_owned_parsers
;
508 /// Adds parser to internal list, and takes ownership of the
512 /// Adds parser to internal list. Does NOT own the parser reference.
515 void ParseRecord(const DBData
&data
, const IConverter
*ic
);