SBValue.h revision c48ca82920bd333c7ccb6ec0e579207add130296 
1//===-- SBValue.h -----------------------------------------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef LLDB_SBValue_h_
11#define LLDB_SBValue_h_
12
13#include "lldb/API/SBData.h"
14#include "lldb/API/SBDefines.h"
15#include "lldb/API/SBType.h"
16
17
18namespace lldb {
19
20class SBValue
21{
22public:
23    SBValue ();
24
25    SBValue (const lldb::SBValue &rhs);
26
27    lldb::SBValue &
28    operator =(const lldb::SBValue &rhs);
29
30    ~SBValue ();
31
32    bool
33    IsValid();
34
35    void
36    Clear();
37
38    SBError
39    GetError();
40
41    lldb::user_id_t
42    GetID ();
43
44    const char *
45    GetName();
46
47    const char *
48    GetTypeName ();
49
50    size_t
51    GetByteSize ();
52
53    bool
54    IsInScope ();
55
56    lldb::Format
57    GetFormat ();
58
59    void
60    SetFormat (lldb::Format format);
61
62    const char *
63    GetValue ();
64
65    int64_t
66    GetValueAsSigned (lldb::SBError& error, int64_t fail_value=0);
67
68    uint64_t
69    GetValueAsUnsigned (lldb::SBError& error, uint64_t fail_value=0);
70
71    int64_t
72    GetValueAsSigned(int64_t fail_value=0);
73
74    uint64_t
75    GetValueAsUnsigned(uint64_t fail_value=0);
76
77    ValueType
78    GetValueType ();
79
80    bool
81    GetValueDidChange ();
82
83    const char *
84    GetSummary ();
85
86    const char *
87    GetObjectDescription ();
88
89    lldb::SBValue
90    GetDynamicValue (lldb::DynamicValueType use_dynamic);
91
92    lldb::SBValue
93    GetStaticValue ();
94
95    bool
96    IsDynamic();
97
98    const char *
99    GetLocation ();
100
101    bool
102    SetValueFromCString (const char *value_str);
103
104    lldb::SBTypeFormat
105    GetTypeFormat ();
106
107#ifndef LLDB_DISABLE_PYTHON
108    lldb::SBTypeSummary
109    GetTypeSummary ();
110#endif
111
112    lldb::SBTypeFilter
113    GetTypeFilter ();
114
115#ifndef LLDB_DISABLE_PYTHON
116    lldb::SBTypeSynthetic
117    GetTypeSynthetic ();
118#endif
119
120    lldb::SBValue
121    GetChildAtIndex (uint32_t idx);
122
123    lldb::SBValue
124    CreateChildAtOffset (const char *name, uint32_t offset, lldb::SBType type);
125
126    lldb::SBValue
127    Cast (lldb::SBType type);
128
129    lldb::SBValue
130    CreateValueFromExpression (const char *name, const char* expression);
131
132    lldb::SBValue
133    CreateValueFromAddress (const char* name,
134                            lldb::addr_t address,
135                            lldb::SBType type);
136
137    // this has no address! GetAddress() and GetLoadAddress() as well as AddressOf()
138    // on the return of this call all return invalid
139    lldb::SBValue
140    CreateValueFromData (const char* name,
141                         lldb::SBData data,
142                         lldb::SBType type);
143
144    //------------------------------------------------------------------
145    /// Get a child value by index from a value.
146    ///
147    /// Structs, unions, classes, arrays and and pointers have child
148    /// values that can be access by index.
149    ///
150    /// Structs and unions access child members using a zero based index
151    /// for each child member. For
152    ///
153    /// Classes reserve the first indexes for base classes that have
154    /// members (empty base classes are omitted), and all members of the
155    /// current class will then follow the base classes.
156    ///
157    /// Pointers differ depending on what they point to. If the pointer
158    /// points to a simple type, the child at index zero
159    /// is the only child value available, unless \a synthetic_allowed
160    /// is \b true, in which case the pointer will be used as an array
161    /// and can create 'synthetic' child values using positive or
162    /// negative indexes. If the pointer points to an aggregate type
163    /// (an array, class, union, struct), then the pointee is
164    /// transparently skipped and any children are going to be the indexes
165    /// of the child values within the aggregate type. For example if
166    /// we have a 'Point' type and we have a SBValue that contains a
167    /// pointer to a 'Point' type, then the child at index zero will be
168    /// the 'x' member, and the child at index 1 will be the 'y' member
169    /// (the child at index zero won't be a 'Point' instance).
170    ///
171    /// Arrays have a preset number of children that can be accessed by
172    /// index and will returns invalid child values for indexes that are
173    /// out of bounds unless the \a synthetic_allowed is \b true. In this
174    /// case the array can create 'synthetic' child values for indexes
175    /// that aren't in the array bounds using positive or negative
176    /// indexes.
177    ///
178    /// @param[in] idx
179    ///     The index of the child value to get
180    ///
181    /// @param[in] use_dynamic
182    ///     An enumeration that specifies wether to get dynamic values,
183    ///     and also if the target can be run to figure out the dynamic
184    ///     type of the child value.
185    ///
186    /// @param[in] synthetic_allowed
187    ///     If \b true, then allow child values to be created by index
188    ///     for pointers and arrays for indexes that normally wouldn't
189    ///     be allowed.
190    ///
191    /// @return
192    ///     A new SBValue object that represents the child member value.
193    //------------------------------------------------------------------
194    lldb::SBValue
195    GetChildAtIndex (uint32_t idx,
196                     lldb::DynamicValueType use_dynamic,
197                     bool can_create_synthetic);
198
199    // Matches children of this object only and will match base classes and
200    // member names if this is a clang typed object.
201    uint32_t
202    GetIndexOfChildWithName (const char *name);
203
204    // Matches child members of this object and child members of any base
205    // classes.
206    lldb::SBValue
207    GetChildMemberWithName (const char *name);
208
209    // Matches child members of this object and child members of any base
210    // classes.
211    lldb::SBValue
212    GetChildMemberWithName (const char *name, lldb::DynamicValueType use_dynamic);
213
214    // Expands nested expressions like .a->b[0].c[1]->d
215    lldb::SBValue
216    GetValueForExpressionPath(const char* expr_path);
217
218    lldb::SBValue
219    AddressOf();
220
221    lldb::addr_t
222    GetLoadAddress();
223
224    lldb::SBAddress
225    GetAddress();
226
227    //------------------------------------------------------------------
228    /// Get an SBData wrapping what this SBValue points to.
229    ///
230    /// This method will dereference the current SBValue, if its
231    /// data type is a T* or T[], and extract item_count elements
232    /// of type T from it, copying their contents in an SBData.
233    ///
234    /// @param[in] item_idx
235    ///     The index of the first item to retrieve. For an array
236    ///     this is equivalent to array[item_idx], for a pointer
237    ///     to *(pointer + item_idx). In either case, the measurement
238    ///     unit for item_idx is the sizeof(T) rather than the byte
239    ///
240    /// @param[in] item_count
241    ///     How many items should be copied into the output. By default
242    ///     only one item is copied, but more can be asked for.
243    ///
244    /// @return
245    ///     An SBData with the contents of the copied items, on success.
246    ///     An empty SBData otherwise.
247    //------------------------------------------------------------------
248    lldb::SBData
249    GetPointeeData (uint32_t item_idx = 0,
250                    uint32_t item_count = 1);
251
252    //------------------------------------------------------------------
253    /// Get an SBData wrapping the contents of this SBValue.
254    ///
255    /// This method will read the contents of this object in memory
256    /// and copy them into an SBData for future use.
257    ///
258    /// @return
259    ///     An SBData with the contents of this SBValue, on success.
260    ///     An empty SBData otherwise.
261    //------------------------------------------------------------------
262    lldb::SBData
263    GetData ();
264
265    uint32_t
266    GetNumChildren ();
267
268    void *
269    GetOpaqueType();
270
271    lldb::SBTarget
272    GetTarget();
273
274    lldb::SBProcess
275    GetProcess();
276
277    lldb::SBThread
278    GetThread();
279
280    lldb::SBFrame
281    GetFrame();
282
283    lldb::SBValue
284    Dereference ();
285
286    bool
287    TypeIsPointerType ();
288
289    lldb::SBType
290    GetType();
291
292    bool
293    GetDescription (lldb::SBStream &description);
294
295    bool
296    GetExpressionPath (lldb::SBStream &description);
297
298    bool
299    GetExpressionPath (lldb::SBStream &description,
300                       bool qualify_cxx_base_classes);
301
302    SBValue (const lldb::ValueObjectSP &value_sp);
303
304    //------------------------------------------------------------------
305    /// Watch this value if it resides in memory.
306    ///
307    /// Sets a watchpoint on the value.
308    ///
309    /// @param[in] resolve_location
310    ///     Resolve the location of this value once and watch its address.
311    ///     This value must currently be set to \b true as watching all
312    ///     locations of a variable or a variable path is not yet supported,
313    ///     though we plan to support it in the future.
314    ///
315    /// @param[in] read
316    ///     Stop when this value is accessed.
317    ///
318    /// @param[in] write
319    ///     Stop when this value is modified
320    ///
321    /// @return
322    ///     An SBWatchpoint object. This object might not be valid upon
323    ///     return due to a value not being contained in memory, too
324    ///     large, or watchpoint resources are not available or all in
325    ///     use.
326    //------------------------------------------------------------------
327    lldb::SBWatchpoint
328    Watch (bool resolve_location, bool read, bool write);
329
330    //------------------------------------------------------------------
331    /// Watch this value that this value points to in memory
332    ///
333    /// Sets a watchpoint on the value.
334    ///
335    /// @param[in] resolve_location
336    ///     Resolve the location of this value once and watch its address.
337    ///     This value must currently be set to \b true as watching all
338    ///     locations of a variable or a variable path is not yet supported,
339    ///     though we plan to support it in the future.
340    ///
341    /// @param[in] read
342    ///     Stop when this value is accessed.
343    ///
344    /// @param[in] write
345    ///     Stop when this value is modified
346    ///
347    /// @return
348    ///     An SBWatchpoint object. This object might not be valid upon
349    ///     return due to a value not being contained in memory, too
350    ///     large, or watchpoint resources are not available or all in
351    ///     use.
352    //------------------------------------------------------------------
353    lldb::SBWatchpoint
354    WatchPointee (bool resolve_location, bool read, bool write);
355
356    // this must be defined in the .h file because synthetic children as implemented in the core
357    // currently rely on being able to extract the SharedPointer out of an SBValue. if the implementation
358    // is deferred to the .cpp file instead of being inlined here, the platform will fail to link
359    // correctly. however, this is temporary till a better general solution is found. FIXME
360    lldb::ValueObjectSP&
361    get_sp()
362    {
363        return m_opaque_sp;
364    }
365
366protected:
367    friend class SBValueList;
368    friend class SBFrame;
369
370    lldb::ValueObjectSP
371    GetSP () const;
372
373    void
374    SetSP (const lldb::ValueObjectSP &sp);
375
376private:
377    lldb::ValueObjectSP m_opaque_sp;
378};
379
380} // namespace lldb
381
382#endif  // LLDB_SBValue_h_
383