1
/******************************************************************************
3
* Purpose: Documentation for the PCIDSKChannel class.
5
******************************************************************************
7
* PCI Geomatics, 50 West Wilmot Street, Richmond Hill, Ont, Canada
9
* Permission is hereby granted, free of charge, to any person obtaining a
10
* copy of this software and associated documentation files (the "Software"),
11
* to deal in the Software without restriction, including without limitation
12
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
13
* and/or sell copies of the Software, and to permit persons to whom the
14
* Software is furnished to do so, subject to the following conditions:
16
* The above copyright notice and this permission notice shall be included
17
* in all copies or substantial portions of the Software.
19
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
20
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25
* DEALINGS IN THE SOFTWARE.
26
****************************************************************************/
30
******************************************************************************
31
\class PCIDSK::PCIDSKSegment
33
This class interface is used for access to PCIDSK segments and associated
34
data. The class should never be instantiated by the application. Instead
35
all instances are owned by the corresponding PCIDSK::PCIDSKFile object
36
and a pointer can be fetched using PCIDSKFile::GetSegment() or related
39
Some segments types such as binary (SEG_BIN) provide no custom interfaces
40
and can only be accessed using the generic PCIDSKSegment methods. Others,
41
such as georeferencing segments (SEG_GEO) offer additional segment specific
42
interfaces via multiple inheritance. Use dynamic casts to get access to
43
the type specific interfaces.
48
PCIDSK::PCIDSKSegment *seg = file->GetSegment(1);
50
if( seg->GetSegmentType() == PCIDSK::SEG_GEO )
52
PCIDSK::PCIDSKGeoref *georef = dynamic_cast<PCIDSK::PCIDSKGeoref*>( seg );
54
printf( "Geosys = %s\n", georef->GetGeosys() );
58
******************************************************************************
59
\fn void PCIDSK::PCIDSKSegment::WriteToFile( const void *buffer, uint64 offset, uint64 size);
61
\brief Write data to segment.
63
Write to data area of this segment. Offset zero refers to the start of the
64
data area of the segment, access to to the segment header is not available
67
@param buffer pointer to the data to write to disk.
68
@param offset the byte offset in the file (zero based) at which to write the data.
69
@param size the number of bytes from buffer to write.
72
******************************************************************************
73
\fn void PCIDSK::PCIDSKSegment::ReadFromFile( void *buffer, uint64 offset, uint64 size);
75
\brief Read data from segment.
77
Read from data area of this segment. Offset zero refers to the start of the
78
data area of the segment, access to to the segment header is not available
81
@param buffer pointer to the buffer into which the data should be read.
82
@param offset the byte offset in the file (zero based) at which to read the data.
83
@param size the number of bytes from the file to read.
85
******************************************************************************
86
\fn eSegType PCIDSK::PCIDSKSegment::GetSegmentType();
88
\brief Fetch segment type.
90
@return the type of this segment.
92
******************************************************************************
93
\fn const char *PCIDSK::PCIDSKSegment::GetName();
95
\brief Fetch segment name.
97
The returned pointer is to internally managed data of the PCIDSKSegment, and
98
should not be modified, freed, or used after the segment object ceases to exist.
99
The name is at most eight characters long.
101
@return the segment name.
103
******************************************************************************
104
\fn const char *PCIDSK::PCIDSKSegment::GetDescription();
106
\brief Fetch segment description.
108
The returned pointer is to internally managed data of the PCIDSKSegment, and
109
should not be modified, freed, or used after the segment object ceases to exist.
110
The description is at most 80 characters long.
112
@return the segment description.
114
******************************************************************************
115
\fn int PCIDSK::PCIDSKSegment::GetSegmentNumber();
117
\brief Fetch segment number.
119
@return the segment number (1+).
121
******************************************************************************
122
\fn std::vector<std::string> PCIDSK::PCIDSKSegment::GetMetadataKeys();
124
\brief Fetch metadata keys
126
Returns a vector of metadata keys that occur on this object. The values
127
associated with each may be fetched with GetMetadataValue().
131
@see GetMetadataValue()
133
******************************************************************************
134
\fn std::string PCIDSK::PCIDSKSegment::GetMetadataValue( std::string key );
136
\brief Fetch metadata value
138
Note that the returned pointer is to an internal structure and it may become
139
invalid if another thread modifies the metadata for this object.
141
@param key the key to fetch the value for.
143
@return the value of the indicated metadata item, or NULL if it does not
144
exist on the target object.
146
@see GetMetadataKeys()
148
******************************************************************************
149
\fn void PCIDSK::PCIDSKSegment::SetMetadataValue( std::string key, std::string value );
151
\brief Set metadata value
153
Assign the metadata value associated with the passed key on this object.
154
The file needs to be open for update. Note that keys should be well formed
155
tokens (no special characters, spaces, etc).
157
@param key the key to fetch the value for.
159
@param value the value to assign to the key. An empty string deletes the item.
161
@see GetMetadataValue()
163
******************************************************************************
164
\fn bool PCIDSK::PCIDSKSegment::IsAtEOF();
166
\brief Is segment last in file?
168
Returns true if the segment is the last one in the file, and thus can be
169
grown without having to move it. Primarily this method is used by the
172
@return true if segment at EOF or false otherwise.
174
******************************************************************************
175
\fn uint64 PCIDSK::PCIDSKSegment::GetContentSize();
177
\brief Get size of segment data.
179
Returns the size of the data portion of this segment (header excluded)
182
@return segment data size in bytes.
184
******************************************************************************
185
\fn void PCIDSK::PCIDSKSegment::Synchronize();
187
\brief Write pending information to disk.
189
Some write and update operations on PCIDSK files are not written to disk
190
immediately after write calls. This method will ensure that any pending
191
writes are flushed through to disk.
193
NOTE: Currently this method does not invalidate read-cached information.
194
At some point in the future it might be extended to do this as well.
added
removed
frmts/pcidsk/sdk/pcidsksegment.dox
